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
12
13       upsmon [-D] [-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 (slave or master).
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 master 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       -D
44           Raise the debugging level. upsmon will run in the foreground and
45           prints information on stdout about the monitoring process. Use this
46           multiple times for more details.
47
48       -K
49           Test for the shutdown flag. If it exists and contains the magic
50           string from upsmon, then upsmon will exit with EXIT_SUCCESS. Any
51           other condition will make upsmon exit with EXIT_FAILURE.
52
53           You can test for a successful exit from upsmon -K in your shutdown
54           scripts to know when to call upsdrvctl(8) to shut down the UPS.
55
56       -p
57           Run privileged all the time. Normally upsmon will split into two
58           processes. The majority of the code runs as an unprivileged user,
59           and only a tiny stub runs as root. This switch will disable that
60           mode, and run the old "all root all the time" system.
61
62           This is not the recommended mode, and you should not use this
63           unless you have a very good reason.
64
65       -u user
66           Set the user for the unprivileged monitoring process. This has no
67           effect when using -p.
68
69           The default user is set at configure time with configure
70           --with-user=.... Typically this is nobody, but other distributions
71           will probably have a specific nut user for this task. If your
72           notification scripts need to run as a specific user, set it here.
73
74           You can also set this in the upsmon.conf(5) file with the
75           RUN_AS_USER directive.
76

UPS DEFINITIONS

78       In the upsmon.conf(5), you must specify at least one UPS that will be
79       monitored. Use the MONITOR directive.
80
81           MONITOR 'system' 'powervalue' 'username' 'password' 'type'
82
83       The system refers to a upsd(8) server, in the form
84       upsname[@hostname[:port]]. The default hostname is "localhost". Some
85       examples follow:
86
87       ·   "su700@mybox" means a UPS called "su700" on a system called
88           "mybox". This is the normal form.
89
90       ·   "fenton@bigbox:5678" is a UPS called "fenton" on a system called
91           "bigbox" which runs upsd(8) on port "5678".
92
93       The powervalue refers to how many power supplies on this system are
94       being driven this UPS. This is typically set to 1, but see the section
95       on power values below.
96
97       The username is a section in your upsd.users(5) file. Whatever password
98       you set in that section must match the password set in this file.
99
100       The type set in that section must also match the type here-- master or
101       slave. In general, a master process is one running on the system with
102       the UPS actually plugged into a serial port, and a slave is drawing
103       power from the UPS but can’t talk to it directly. See the section on
104       UPS types for more.
105

NOTIFY EVENTS

107       upsmon senses several events as it monitors each UPS. They are called
108       notify events as they can be used to tell the users and admins about
109       the change in status. See the additional NOTIFY-related sections below
110       for information on customizing the delivery of these messages.
111
112       ONLINE
113           The UPS is back on line.
114
115       ONBATT
116           The UPS is on battery.
117
118       LOWBATT
119           The UPS battery is low (as determined by the driver).
120
121       FSD
122           The UPS has been commanded into the "forced shutdown" mode.
123
124       COMMOK
125           Communication with the UPS has been established.
126
127       COMMBAD
128           Communication with the UPS was just lost.
129
130       SHUTDOWN
131           The local system is being shut down.
132
133       REPLBATT
134           The UPS needs to have its battery replaced.
135
136       NOCOMM
137           The UPS can’t be contacted for monitoring.
138

NOTIFY COMMAND

140       In upsmon.conf(5), you can configure a program called the NOTIFYCMD
141       that will handle events that occur.
142
143       NOTIFYCMD "path to program"
144
145       NOTIFYCMD "/usr/local/bin/notifyme"
146
147       Remember to wrap the path in "quotes" if it contains any spaces.
148
149       The program you run as your NOTIFYCMD can use the environment variables
150       NOTIFYTYPE and UPSNAME to know what has happened and on which UPS. It
151       also receives the notification message (see below) as the first (and
152       only) argument, so you can deliver a preformatted message too.
153
154       Note that the NOTIFYCMD will only be called for a given event when you
155       set the EXEC flag by using the notify flags, below:
156

NOTIFY FLAGS

158       By default, all notify events (see above) generate a global message
159       (wall) to all users, plus they are logged via the syslog. You can
160       change this with the NOTIFYFLAG directive in the configuration file:
161
162       NOTIFYFLAG notifytype flags
163
164       Examples:
165
166       ·   NOTIFYFLAG ONLINE SYSLOG
167
168       ·   NOTIFYFLAG ONBATT SYSLOG+WALL
169
170       ·   NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC
171
172       The flags that can be set on a given notify event are:
173
174       SYSLOG
175           Write this message to the syslog.
176
177       WALL
178           Send this message to all users on the system via wall(1).
179
180       EXEC
181           Execute the NOTIFYCMD.
182
183       IGNORE
184           Don’t do anything. If you use this, don’t use any of the other
185           flags.
186
187       You can mix these flags. "SYSLOG+WALL+EXEC" does all three for a given
188       event.
189

NOTIFY MESSAGES

191       upsmon comes with default messages for each of the NOTIFY events. These
192       can be changed with the NOTIFYMSG directive.
193
194       NOTIFYMSG type "message"
195
196       Examples:
197
198       ·   NOTIFYMSG ONLINE "UPS %s is getting line power"
199
200       ·   ` NOTIFYMSG ONBATT "Someone pulled the plug on %s"`
201
202       The first instance of %s is replaced with the identifier of the UPS
203       that generated the event. These messages are used when sending walls to
204       the users directly from upsmon, and are also passed to the NOTIFYCMD.
205

POWER VALUES

207       The "current overall power value" is the sum of all UPSes that are
208       currently able to supply power to the system hosting upsmon. Any UPS
209       that is either on line or just on battery contributes to this number.
210       If a UPS is critical (on battery and low battery) or has been put into
211       "forced shutdown" mode, it no longer contributes.
212
213       A "power value" on a MONITOR line in the config file is the number of
214       power supplies that the UPS runs on the current system.
215
216       MONITOR upsname powervalue username password type
217
218       Normally, you only have one power supply, so it will be set to 1.
219
220       MONITOR myups@myhost 1 username mypassword master
221
222       On a large server with redundant power supplies, the power value for a
223       UPS may be greater than 1. You may also have more than one of them
224       defined.
225
226       MONITOR ups-alpha@myhost 2 username mypassword master
227
228       MONITOR ups-beta@myhost 2 username mypassword master
229
230       You can also set the power value for a UPS to 0 if it does not supply
231       any power to that system. This is generally used when you want to use
232       the upsmon notification features for a UPS even though it’s not
233       actually running the system that hosts upsmon. Don’t set this to
234       "master" unless you really want to power this UPS off when this
235       instance of upsmon needs to shut down for its own reasons.
236
237       MONITOR faraway@anotherbox 0 username mypassword slave
238
239       The "minimum power value" is the number of power supplies that must be
240       receiving power in order to keep the computer running.
241
242       MINSUPPLIES value
243
244       Typical PCs only have 1, so most users will leave this at the default.
245
246       MINSUPPLIES 1
247
248       If you have a server or similar system with redundant power, then this
249       value will usually be set higher. One that requires three power
250       supplies to be running at all times would simply set it to 3.
251
252       MINSUPPLIES 3
253
254       When the current overall power value drops below the minimum power
255       value, upsmon starts the shutdown sequence. This design allows you to
256       lose some of your power supplies in a redundant power environment
257       without bringing down the entire system while still working properly
258       for smaller systems.
259

UPS TYPES

261       upsmon and upsd(8) don’t always run on the same system. When they do,
262       any UPSes that are directly attached to the upsmon host should be
263       monitored in "master" mode. This makes upsmon take charge of that
264       equipment, and it will wait for slaves to disconnect before shutting
265       down the local system. This allows the distant systems (monitoring over
266       the network) to shut down cleanly before upsdrvctl shutdown runs and
267       turns them all off.
268
269       When upsmon runs as a slave, it is relying on the distant system to
270       tell it about the state of the UPS. When that UPS goes critical (on
271       battery and low battery), it immediately invokes the local shutdown
272       command. This needs to happen quickly. Once it disconnects from the
273       distant upsd(8) server, the master upsmon will start its own shutdown
274       process. Your slaves must all shut down before the master turns off the
275       power or filesystem damage may result.
276
277       upsmon deals with slaves that get wedged, hang, or otherwise fail to
278       disconnect from upsd(8) in a timely manner with the HOSTSYNC timer.
279       During a shutdown situation, the master upsmon will give up after this
280       interval and it will shut down anyway. This keeps the master from
281       sitting there forever (which would endanger that host) if a slave
282       should break somehow. This defaults to 15 seconds.
283
284       If your master system is shutting down too quickly, set the FINALDELAY
285       interval to something greater than the default 15 seconds. Don’t set
286       this too high, or your UPS battery may run out of power before the
287       master upsmon process shuts down that system.
288

TIMED SHUTDOWNS

290       For those rare situations where the shutdown process can’t be completed
291       between the time that low battery is signalled and the UPS actually
292       powers off the load, use the upssched(8) helper program. You can use it
293       along with upsmon to schedule a shutdown based on the "on battery"
294       event. upssched can then come back to upsmon to initiate the shutdown
295       once it has run on battery too long.
296
297       This can be complicated and messy, so stick to the default critical UPS
298       handling if you can.
299

REDUNDANT POWER SUPPLIES

301       If you have more than one power supply for redundant power, you may
302       also have more than one UPS feeding your computer. upsmon can handle
303       this. Be sure to set the UPS power values appropriately and the
304       MINSUPPLIES value high enough so that it keeps running until it really
305       does need to shut down.
306
307       For example, the HP NetServer LH4 by default has 3 power supplies
308       installed, with one bay empty. It has two power cords, one per side of
309       the box. This means that one power cord powers two power supply bays,
310       and that you can only have two UPSes supplying power.
311
312       Connect UPS "alpha" to the cord feeding two power supplies, and UPS
313       "beta" to the cord that feeds the third and the empty slot. Define
314       alpha as a powervalue of 2, and beta as a powervalue of 1. Set the
315       MINSUPPLIES to 2.
316
317       When alpha goes on battery, your current overall power value will stay
318       at 3, as it’s still supplying power. However, once it goes critical (on
319       battery and low battery), it will stop contributing to the current
320       overall power value. That means the value will be 1 (beta alone), which
321       is less than 2. That is insufficient to run the system, and upsmon will
322       invoke the shutdown sequence.
323
324       However, if beta goes critical, subtracting its contribution will take
325       the current overall value from 3 to 2. This is just high enough to
326       satisfy the minimum, so the system will continue running as before. If
327       beta returns later, it will be re-added and the current value will go
328       back to 3. This allows you to swap out UPSes, change a power
329       configuration, or whatever, as long as you maintain the minimum power
330       value at all times.
331

MIXED OPERATIONS

333       Besides being able to monitor multiple UPSes, upsmon can also monitor
334       them as different roles. If you have a system with multiple power
335       supplies serviced by separate UPS batteries, it’s possible to be a
336       master on one and a slave on the other. This usually happens when you
337       run out of serial ports and need to do the monitoring through another
338       system nearby.
339
340       This is also complicated, especially when it comes time to power down a
341       UPS that has gone critical but doesn’t supply the local system. You can
342       do this with some scripting magic in your notify command script, but
343       it’s beyond the scope of this manual.
344

FORCED SHUTDOWNS

346       When upsmon is forced to bring down the local system, it sets the "FSD"
347       (forced shutdown) flag on any UPSes that it is running in master mode.
348       This is used to synchronize slaves in the event that a master UPS that
349       is otherwise OK needs to be brought down due to some pressing event on
350       the master.
351
352       You can manually invoke this mode on the master upsmon by starting
353       another copy with -c fsd. This is useful when you want to initiate a
354       shutdown before the critical stage through some external means, such as
355       upssched(8).
356

DEAD UPSES

358       In the event that upsmon can’t reach upsd(8), it declares that UPS
359       "dead" after some interval controlled by DEADTIME in the
360       upsmon.conf(5). If this happens while that UPS was last known to be on
361       battery, it is assumed to have gone critical and no longer contributes
362       to the overall power value.
363
364       upsmon will alert you to a UPS that can’t be contacted for monitoring
365       with a "NOCOMM" notifier by default every 300 seconds. This can be
366       changed with the NOCOMMWARNTIME setting.
367

RELOADING NUANCES

369       upsmon usually gives up root powers for the process that does most of
370       the work, including handling signals like SIGHUP to reload the
371       configuration file. This means your upsmon.conf(8) file must be
372       readable by the non-root account that upsmon switches to.
373
374       If you want reloads to work, upsmon must run as some user that has
375       permissions to read the configuration file. I recommend making a new
376       user just for this purpose, as making the file readable by "nobody"
377       (the default user) would be a bad idea.
378
379       See the RUN_AS_USER section in upsmon.conf(8) for more on this topic.
380
381       Additionally, you can’t change the SHUTDOWNCMD or POWERDOWNFLAG
382       definitions with a reload due to the split-process model. If you change
383       those values, you must stop upsmon and start it back up. upsmon will
384       warn you in the syslog if you make changes to either of those values
385       during a reload.
386

SIMULATING POWER FAILURES

388       To test a synchronized shutdown without pulling the plug on your
389       UPS(es), you need only set the forced shutdown (FSD) flag on them. You
390       can do this by calling upsmon again to set the flag, i.e.:
391
392       upsmon -c fsd
393
394       After that, the master and the slaves will do their usual shutdown
395       sequence as if the battery had gone critical. This is much easier on
396       your UPS equipment, and it beats crawling under a desk to find the
397       plug.
398

FILES

400       upsmon.conf(5)
401

SEE ALSO

403   Server:
404       upsd(8)
405
406   Clients:
407       upsc(8), upscmd(8), upsrw(8), upsmon(8)
408
409   CGI programs:
410       upsset.cgi(8), upsstats.cgi(8), upsimage.cgi(8)
411
412   Internet resources:
413       The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
414
415
416
417Network UPS Tools 2.7.3.          12/29/2015                         UPSMON(8)
Impressum