1UPSMON.CONF(5)                    NUT Manual                    UPSMON.CONF(5)
2
3
4

NAME

6       upsmon.conf - Configuration for Network UPS Tools upsmon
7

DESCRIPTION

9       This file’s primary job is to define the systems that upsmon(8) will
10       monitor and to tell it how to shut down the system when necessary. It
11       will contain passwords, so keep it secure. Ideally, only the upsmon
12       process should be able to read it.
13
14       Additionally, other optional configuration values can be set in this
15       file.
16

CONFIGURATION DIRECTIVES

18       DEADTIME seconds
19           upsmon allows a UPS to go missing for this many seconds before
20           declaring it "dead". The default is 15 seconds.
21
22           upsmon requires a UPS to provide status information every few
23           seconds (see POLLFREQ and POLLFREQALERT) to keep things updated. If
24           the status fetch fails, the UPS is marked stale. If it stays stale
25           for more than DEADTIME seconds, the UPS is marked dead.
26
27           A dead UPS that was last known to be on battery is assumed to have
28           changed to a low battery condition. This may force a shutdown if it
29           is providing a critical amount of power to your system. This seems
30           disruptive, but the alternative is barreling ahead into oblivion
31           and crashing when you run out of power.
32
33           Note: DEADTIME should be a multiple of POLLFREQ and POLLFREQALERT.
34           Otherwise, you’ll have "dead" UPSes simply because upsmon isn’t
35           polling them quickly enough. Rule of thumb: take the larger of the
36           two POLLFREQ values, and multiply by 3.
37
38       FINALDELAY seconds
39           When running in master mode, upsmon waits this long after sending
40           the NOTIFY_SHUTDOWN to warn the users. After the timer elapses, it
41           then runs your SHUTDOWNCMD. By default this is set to 5 seconds.
42
43           If you need to let your users do something in between those events,
44           increase this number. Remember, at this point your UPS battery is
45           almost depleted, so don’t make this too big.
46
47           Alternatively, you can set this very low so you don’t wait around
48           when it’s time to shut down. Some UPSes don’t give much warning for
49           low battery and will require a value of 0 here for a safe shutdown.
50
51               Note
52               If FINALDELAY on the slave is greater than HOSTSYNC on the
53               master, the master will give up waiting for the slave to
54               disconnect.
55
56       HOSTSYNC seconds
57           upsmon will wait up to this many seconds in master mode for the
58           slaves to disconnect during a shutdown situation. By default, this
59           is 15 seconds.
60
61           When a UPS goes critical (on battery + low battery, or "FSD":
62           forced shutdown), the slaves are supposed to disconnect and shut
63           down right away. The HOSTSYNC timer keeps the master upsmon from
64           sitting there forever if one of the slaves gets stuck.
65
66           This value is also used to keep slave systems from getting stuck if
67           the master fails to respond in time. After a UPS becomes critical,
68           the slave will wait up to HOSTSYNC seconds for the master to set
69           the FSD flag. If that timer expires, the slave will assume that the
70           master is broken and will shut down anyway.
71
72           This keeps the slaves from shutting down during a short-lived
73           status change to "OB LB" that the slaves see but the master misses.
74
75       MINSUPPLIES num
76           Set the number of power supplies that must be receiving power to
77           keep this system running. Normal computers have just one power
78           supply, so the default value of 1 is acceptable.
79
80           Large/expensive server type systems usually have more, and can run
81           with a few missing. The HP NetServer LH4 can run with 2 out of 4,
82           for example, so you’d set it to 2. The idea is to keep the box
83           running as long as possible, right?
84
85           Obviously you have to put the redundant supplies on different UPS
86           circuits for this to make sense! See big-servers.txt in the docs
87           subdirectory for more information and ideas on how to use this
88           feature.
89
90           Also see the section on "power values" in upsmon(8).
91
92       MONITOR system powervalue username password type
93           Each UPS that you need to be monitor should have a MONITOR line.
94           Not all of these need supply power to the system that is running
95           upsmon. You may monitor other systems if you want to be able to
96           send notifications about status changes on them.
97
98       You must have at least one MONITOR directive in upsmon.conf.
99
100       system is a UPS identifier. It is in this form:
101
102       <upsname>[@<hostname>[:<port>]]
103
104       The default hostname is "localhost". Some examples:
105
106       ·   "su700@mybox" means a UPS called "su700" on a system called
107           "mybox". This is the normal form.
108
109       ·   "fenton@bigbox:5678" is a UPS called "fenton" on a system called
110           "bigbox" which runs upsd(8) on port "5678".
111
112       powervalue is an integer representing the number of power supplies that
113       the UPS feeds on this system. Most normal computers have one power
114       supply, and the UPS feeds it, so this value will be 1. You need a very
115       large or special system to have anything higher here.
116
117       You can set the powervalue to 0 if you want to monitor a UPS that
118       doesn’t actually supply power to this system. This is useful when you
119       want to have upsmon do notifications about status changes on a UPS
120       without shutting down when it goes critical.
121
122       The username and password on this line must match an entry in that
123       system’s upsd.users(5). If your username is "monmaster" and your
124       password is "blah", the MONITOR line might look like this:
125
126       MONITOR myups@bigserver 1 monmaster blah master
127
128       Meanwhile, the upsd.users on bigserver would look like this:
129
130           [monmaster]
131                   password  = blah
132                   upsmon master #  (or slave)
133
134       The type refers to the relationship with upsd(8). It can be either
135       "master" or "slave". See upsmon(8) for more information on the meaning
136       of these modes. The mode you pick here also goes in the upsd.users
137       file, as seen in the example above.
138
139       NOCOMMWARNTIME seconds
140           upsmon will trigger a NOTIFY_NOCOMM after this many seconds if it
141           can’t reach any of the UPS entries in this configuration file. It
142           keeps warning you until the situation is fixed. By default this is
143           300 seconds.
144
145       NOTIFYCMD command
146           upsmon calls this to send messages when things happen.
147
148           This command is called with the full text of the message as one
149           argument. The environment string NOTIFYTYPE will contain the type
150           string of whatever caused this event to happen.
151
152           If you need to use upssched(8), then you must make it your
153           NOTIFYCMD by listing it here.
154
155           Note that this is only called for NOTIFY events that have EXEC set
156           with NOTIFYFLAG. See NOTIFYFLAG below for more details.
157
158           Making this some sort of shell script might not be a bad idea. For
159           more information and ideas, see docs/scheduling.txt
160
161           Remember, this command also needs to be one element in the
162           configuration file, so if your command has spaces, then wrap it in
163           quotes.
164
165           NOTIFYCMD "/path/to/script --foo --bar"
166
167           This script is run in the background—that is, upsmon forks before
168           it calls out to start it. This means that your NOTIFYCMD may have
169           multiple instances running simultaneously if a lot of stuff happens
170           all at once. Keep this in mind when designing complicated
171           notifiers.
172
173       NOTIFYMSG type message
174           upsmon comes with a set of stock messages for various events. You
175           can change them if you like.
176
177               NOTIFYMSG ONLINE "UPS %s is getting line power"
178
179               NOTIFYMSG ONBATT "Someone pulled the plug on %s"
180
181           Note that %s is replaced with the identifier of the UPS in
182           question.
183
184           The message must be one element in the configuration file, so if it
185           contains spaces, you must wrap it in quotes.
186
187               NOTIFYMSG NOCOMM "Someone stole UPS %s"
188
189           Possible values for type:
190
191           ONLINE
192               UPS is back online
193
194           ONBATT
195               UPS is on battery
196
197           LOWBATT
198               UPS is on battery and has a low battery (is critical)
199
200           FSD
201               UPS is being shutdown by the master (FSD = "Forced Shutdown")
202
203           COMMOK
204               Communications established with the UPS
205
206           COMMBAD
207               Communications lost to the UPS
208
209           SHUTDOWN
210               The system is being shutdown
211
212           REPLBATT
213               The UPS battery is bad and needs to be replaced
214
215           NOCOMM
216               A UPS is unavailable (can’t be contacted for monitoring)
217
218       NOTIFYFLAG type flag[+flag][+flag]...
219           By default, upsmon sends walls global messages to all logged in
220           users) via /bin/wall and writes to the syslog when things happen.
221           You can change this.
222
223           Examples:
224
225               NOTIFYFLAG ONLINE SYSLOG
226               NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
227
228           Possible values for the flags:
229
230           SYSLOG
231               Write the message to the syslog
232
233           WALL
234               Write the message to all users with /bin/wall
235
236           EXEC
237               Execute NOTIFYCMD (see above) with the message
238
239           IGNORE
240               Don’t do anything
241
242               If you use IGNORE, don’t use any other flags on the same line.
243
244       POLLFREQ seconds
245           Normally upsmon polls the upsd(8) server every 5 seconds. If this
246           is flooding your network with activity, you can make it higher. You
247           can also make it lower to get faster updates in some cases.
248
249           There are some catches. First, if you set the POLLFREQ too high,
250           you may miss short-lived power events entirely. You also risk
251           triggering the DEADTIME (see above) if you use a very large number.
252
253           Second, there is a point of diminishing returns if you set it too
254           low. While upsd normally has all of the data available to it
255           instantly, most drivers only refresh the UPS status once every 2
256           seconds. Polling any more than that usually doesn’t get you the
257           information any faster.
258
259       POLLFREQALERT seconds
260           This is the interval that upsmon waits between polls if any of its
261           UPSes are on battery. You can use this along with POLLFREQ above to
262           slow down polls during normal behavior, but get quicker updates
263           when something bad happens.
264
265           This should always be equal to or lower than the POLLFREQ value. By
266           default it is also set 5 seconds.
267
268           The warnings from the POLLFREQ entry about too-high and too-low
269           values also apply here.
270
271       POWERDOWNFLAG filename
272           upsmon creates this file when running in master mode when the UPS
273           needs to be powered off. You should check for this file in your
274           shutdown scripts and call upsdrvctl shutdown if it exists.
275
276           This is done to forcibly reset the slaves, so they don’t get stuck
277           at the "halted" stage even if the power returns during the shutdown
278           process. This usually does not work well on contact-closure UPSes
279           that use the genericups driver.
280
281           See the config-notes.txt file in the docs subdirectory for more
282           information. Refer to the section:
283
284           "Configuring automatic shutdowns for low battery events", or refer
285           to the online version.
286
287       RBWARNTIME seconds
288           When a UPS says that it needs to have its battery replaced, upsmon
289           will generate a NOTIFY_REPLBATT event. By default, this happens
290           every 43200 seconds (12 hours).
291
292           If you need another value, set it here.
293
294       RUN_AS_USER username
295           upsmon normally runs the bulk of the monitoring duties under
296           another user ID after dropping root privileges. On most systems
297           this means it runs as "nobody", since that’s the default from
298           compile-time.
299
300           The catch is that "nobody" can’t read your upsmon.conf, since by
301           default it is installed so that only root can open it. This means
302           you won’t be able to reload the configuration file, since it will
303           be unavailable.
304
305           The solution is to create a new user just for upsmon, then make it
306           run as that user. I suggest "nutmon", but you can use anything that
307           isn’t already taken on your system. Just create a regular user with
308           no special privileges and an impossible password.
309
310           Then, tell upsmon to run as that user, and make upsmon.conf
311           readable by it. Your reloads will work, and your config file will
312           stay secure.
313
314           This file should not be writable by the upsmon user, as it would be
315           possible to exploit a hole, change the SHUTDOWNCMD to something
316           malicious, then wait for upsmon to be restarted.
317
318       SHUTDOWNCMD command
319           upsmon runs this command when the system needs to be brought down.
320           If it is a slave, it will do that immediately whenever the current
321           overall power value drops below the MINSUPPLIES value above.
322
323           When upsmon is a master, it will allow any slaves to log out before
324           starting the local shutdown procedure.
325
326           Note that the command needs to be one element in the config file.
327           If your shutdown command includes spaces, then put it in quotes to
328           keep it together, i.e.:
329
330               SHUTDOWNCMD "/sbin/shutdown -h +0"
331
332       CERTPATH certificate file or database
333           When compiled with SSL support, you can enter the certificate path
334           here.
335
336           With NSS:
337               Certificates are stored in a dedicated database (splitted in 3
338               files). Specify the path of the database directory.
339
340           With OpenSSL:
341               Directory containing CA certificates in PEM format, used to
342               verify the server certificate presented by the upsd server. The
343               files each contain one CA certificate. The files are looked up
344               by the CA subject name hash value, which must hence be
345               available.
346
347       CERTIDENT certificate name database password
348           When compiled with SSL support with NSS, you can specify the
349           certificate name to retrieve from database to authenticate itself
350           and the password required to access certificate related private
351           key.
352
353       CERTHOST hostname certificate name certverify forcessl
354           When compiled with SSL support with NSS, you can specify security
355           directive for each server you can contact.
356
357           Each entry maps server name with the expected certificate name and
358           flags indicating if the server certificate is verified and if the
359           connection must be secure.
360
361       CERTVERIFY 0 | 1
362           When compiled with SSL support, make upsmon verify all connections
363           with certificates.
364
365           Without this, there is no guarantee that the upsd is the right
366           host. Enabling this greatly reduces the risk of man-in-the-middle
367           attacks. This effectively forces the use of SSL, so don’t use this
368           unless all of your upsd hosts are ready for SSL and have their
369           certificates in order.
370
371           When compiled with NSS support of SSL, can be overriden for host
372           specified with a CERTHOST directive.
373
374       FORCESSL 0 | 1
375           When compiled with SSL, specify that a secured connection must be
376           used to communicate with upsd.
377
378           If you don’t use CERTVERIFY 1, then this will at least make sure
379           that nobody can sniff your sessions without a large effort. Setting
380           this will make upsmon drop connections if the remote upsd doesn’t
381           support SSL, so don’t use it unless all of them have it running.
382
383           When compiled with NSS support of SSL, can be overriden for host
384           specified with a CERTHOST directive.
385

SEE ALSO

387       upsmon(8), upsd(8), nutupsdrv(8).
388
389   Internet resources:
390       The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
391
392
393
394Network UPS Tools 2.7.3.          12/29/2015                    UPSMON.CONF(5)
Impressum