1UPSMON(8)                         NUT Manual                         UPSMON(8)
2
3
4

NAME

6       upsmon - UPS monitor and shutdown controller
7

SYNOPSIS

9       upsmon -h
10
11       upsmon -c command [-P pid]
12
13       upsmon [-D] [-F | -B] [-K] [-p] [-u user]
14

DESCRIPTION

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
21       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

OPTIONS

26       -h
27           Display the help message.
28
29       -c command
30           Send the command command to the existing upsmon process. Valid
31           commands are:
32
33           fsd
34               shutdown all primary-mode UPSes (use with caution)
35
36           stop
37               stop monitoring and exit
38
39           reload
40               reread upsmon.conf(5) configuration file. See "reloading
41               nuances" below if this doesn’t work.
42
43       -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
49       -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
54       -F
55           upsmon will run in the foreground, regardless of debugging
56           settings.
57
58       -B
59           upsmon will run in the background, regardless of debugging
60           settings.
61
62       -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
67           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
70       -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
76           This is not the recommended mode, and you should not use this
77           unless you have a very good reason.
78
79       -u user
80           Set the user for the unprivileged monitoring process. This has no
81           effect when using -p.
82
83           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
88           You can also set this in the upsmon.conf(5) file with the
89           RUN_AS_USER directive.
90

UPS DEFINITIONS

92       In the upsmon.conf(5), you must specify at least one UPS that will be
93       monitored. Use the MONITOR directive.
94
95           MONITOR 'system' 'powervalue' 'username' 'password' 'type'
96
97       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
101       •   "su700@mybox" means a UPS called "su700" on a system called
102           "mybox". This is the normal form.
103
104       •   "fenton@bigbox:5678" is a UPS called "fenton" on a system called
105           "bigbox" which runs upsd(8) on port "5678".
106
107       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
111       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
114       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

NOTIFY EVENTS

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
126       ONLINE
127           The UPS is back on line.
128
129       ONBATT
130           The UPS is on battery.
131
132       LOWBATT
133           The UPS battery is low (as determined by the driver).
134
135       FSD
136           The UPS has been commanded into the "forced shutdown" mode.
137
138       COMMOK
139           Communication with the UPS has been established.
140
141       COMMBAD
142           Communication with the UPS was just lost.
143
144       SHUTDOWN
145           The local system is being shut down.
146
147       REPLBATT
148           The UPS needs to have its battery replaced.
149
150       NOCOMM
151           The UPS can’t be contacted for monitoring.
152

NOTIFY COMMAND

154       In upsmon.conf(5), you can configure a program called the NOTIFYCMD
155       that will handle events that occur.
156
157       NOTIFYCMD "path to program"
158
159       NOTIFYCMD "/usr/local/bin/notifyme"
160
161       Remember to wrap the path in "quotes" if it contains any spaces.
162
163       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
168       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

NOTIFY FLAGS

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
176       NOTIFYFLAG notifytype flags
177
178       Examples:
179
180       •   NOTIFYFLAG ONLINE SYSLOG
181
182       •   NOTIFYFLAG ONBATT SYSLOG+WALL
183
184       •   NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC
185
186       The flags that can be set on a given notify event are:
187
188       SYSLOG
189           Write this message to the syslog.
190
191       WALL
192           Send this message to all users on the system via wall(1).
193
194       EXEC
195           Execute the NOTIFYCMD.
196
197       IGNORE
198           Don’t do anything. If you use this, don’t use any of the other
199           flags.
200
201       You can mix these flags. "SYSLOG+WALL+EXEC" does all three for a given
202       event.
203

NOTIFY MESSAGES

205       upsmon comes with default messages for each of the NOTIFY events. These
206       can be changed with the NOTIFYMSG directive.
207
208       NOTIFYMSG type "message"
209
210       Examples:
211
212       •   NOTIFYMSG ONLINE "UPS %s is getting line power"
213
214       •   ` NOTIFYMSG ONBATT "Someone pulled the plug on %s"`
215
216       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

POWER VALUES

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
227       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
230       MONITOR upsname powervalue username password type
231
232       Normally, you only have one power supply, so it will be set to 1.
233
234       MONITOR myups@myhost 1 username mypassword primary
235
236       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
240       MONITOR ups-alpha@myhost 2 username mypassword primary
241
242       MONITOR ups-beta@myhost 2 username mypassword primary
243
244       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
251       MONITOR faraway@anotherbox 0 username mypassword secondary
252
253       The "minimum power value" is the number of power supplies that must be
254       receiving power in order to keep the computer running.
255
256       MINSUPPLIES value
257
258       Typical PCs only have 1, so most users will leave this at the default.
259
260       MINSUPPLIES 1
261
262       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
266       MINSUPPLIES 3
267
268       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

UPS TYPES

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
283       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
292       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
299       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

TIMED SHUTDOWNS

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
312       This can be complicated and messy, so stick to the default critical UPS
313       handling if you can.
314

REDUNDANT POWER SUPPLIES

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
322       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
327       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
332       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
339       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

MIXED OPERATIONS

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
355       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

FORCED SHUTDOWNS

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
367       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

DEAD UPSES

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
379       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

RELOADING NUANCES

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
389       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
394       See the RUN_AS_USER section in upsmon.conf(8) for more on this topic.
395
396       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

SIMULATING POWER FAILURES

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
407       upsmon -c fsd
408
409       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
414       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

FILES

419       upsmon.conf(5)
420

SEE ALSO

422   Server:
423       upsd(8)
424
425   Clients:
426       upsc(8), upscmd(8), upsrw(8), upsmon(8)
427
428   CGI programs:
429       upsset.cgi(8), upsstats.cgi(8), upsimage.cgi(8)
430
431   Internet resources:
432       The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
433
434
435
436Network UPS Tools 2.8.0           04/26/2022                         UPSMON(8)
Impressum