1UPSMON.CONF(5) NUT Manual UPSMON.CONF(5)
2
6 upsmon.conf - Configuration for Network UPS Tools upsmon
7
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 Additionally, other optional configuration values can be set in this
15 file.
16
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 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 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 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 FINALDELAY seconds
39 When running in primary 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 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 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 Note
52 If FINALDELAY on the secondary is greater than HOSTSYNC on the
53 primary, the primary will give up waiting for that secondary
54 upsmon to disconnect.
55 HOSTSYNC seconds
57 upsmon will wait up to this many seconds in primary mode for the
58 secondaries to disconnect during a shutdown situation. By default,
59 this is 15 seconds.
60 When a UPS goes critical (on battery + low battery, or "FSD":
62 forced shutdown), the secondary systems are supposed to disconnect
63 and shut down right away. The HOSTSYNC timer keeps the primary
64 upsmon from sitting there forever if one of the secondaries gets
65 stuck.
66 This value is also used to keep secondary systems from getting
68 stuck if the primary fails to respond in time. After a UPS becomes
69 critical, the secondary will wait up to HOSTSYNC seconds for the
70 primary to set the FSD flag. If that timer expires, the secondary
71 upsmon will assume that the primary (or communications path to it)
72 is broken and will shut down anyway.
73 This keeps the secondaries from shutting down during a short-lived
75 status change to "OB LB" and back that the secondaries see but the
76 primary misses.
77 MINSUPPLIES num
79 Set the number of power supplies that must be receiving power to
80 keep this system running. Normal computers have just one power
81 supply, so the default value of 1 is acceptable.
82 Large/expensive server type systems usually have more, and can run
84 with a few missing. The HP NetServer LH4 can run with 2 out of 4,
85 for example, so you’d set it to 2. The idea is to keep the box
86 running as long as possible, right?
87 Obviously you have to put the redundant supplies on different UPS
89 circuits for this to make sense! See big-servers.txt in the docs
90 subdirectory for more information and ideas on how to use this
91 feature.
92 Also see the section on "power values" in upsmon(8).
94 MONITOR system powervalue username password type
96 Each UPS that you need to be monitor should have a MONITOR line.
97 Not all of these need supply power to the system that is running
98 upsmon. You may monitor other systems if you want to be able to
99 send notifications about status changes on them.
100 You must have at least one MONITOR directive in upsmon.conf.
102 system is a UPS identifier. It is in this form:
104 <upsname>[@<hostname>[:<port>]]
106 The default hostname is "localhost". Some examples:
108 • "su700@mybox" means a UPS called "su700" on a system called
110 "mybox". This is the normal form.
111 • "fenton@bigbox:5678" is a UPS called "fenton" on a system called
113 "bigbox" which runs upsd(8) on port "5678".
114 powervalue is an integer representing the number of power supplies that
116 the UPS feeds on this system. Most normal computers have one power
117 supply, and the UPS feeds it, so this value will be 1. You need a very
118 large or special system to have anything higher here.
119 You can set the powervalue to 0 if you want to monitor a UPS that
121 doesn’t actually supply power to this system. This is useful when you
122 want to have upsmon do notifications about status changes on a UPS
123 without shutting down when it goes critical.
124 The username and password on this line must match an entry in the upsd
126 server system’s upsd.users(5) file.
127 If your username is "observer" and your password is "abcd", the MONITOR
129 line might look like this (likely on a remote secondary system):
130 MONITOR myups@bigserver 1 observer abcd secondary
132 Meanwhile, the upsd.users on bigserver would look like this:
134 [observer]
136 password = abcd
137 upsmon secondary
138 [upswired]
140 password = blah
141 upsmon primary
142 And the copy of upsmon on that bigserver would run with the primary
144 configuration:
145 MONITOR myups@bigserver 1 upswired blah primary
147 The type refers to the relationship with upsd(8). It can be either
149 "primary" or "secondary". See upsmon(8) for more information on the
150 meaning of these modes. The mode you pick here also goes in the
151 upsd.users file, as seen in the example above.
152 NOCOMMWARNTIME seconds
154 upsmon will trigger a NOTIFY_NOCOMM after this many seconds if it
155 can’t reach any of the UPS entries in this configuration file. It
156 keeps warning you until the situation is fixed. By default this is
157 300 seconds.
158 NOTIFYCMD command
160 upsmon calls this to send messages when things happen.
161 This command is called with the full text of the message as one
163 argument. The environment string NOTIFYTYPE will contain the type
164 string of whatever caused this event to happen.
165 If you need to use upssched(8), then you must make it your
167 NOTIFYCMD by listing it here.
168 Note that this is only called for NOTIFY events that have EXEC set
170 with NOTIFYFLAG. See NOTIFYFLAG below for more details.
171 Making this some sort of shell script might not be a bad idea. For
173 more information and ideas, see docs/scheduling.txt
174 Remember, this command also needs to be one element in the
176 configuration file, so if your command has spaces, then wrap it in
177 quotes.
178 NOTIFYCMD "/path/to/script --foo --bar"
180 This script is run in the background—that is, upsmon forks before
182 it calls out to start it. This means that your NOTIFYCMD may have
183 multiple instances running simultaneously if a lot of stuff happens
184 all at once. Keep this in mind when designing complicated
185 notifiers.
186 NOTIFYMSG type message
188 upsmon comes with a set of stock messages for various events. You
189 can change them if you like.
190 NOTIFYMSG ONLINE "UPS %s is getting line power"
192 NOTIFYMSG ONBATT "Someone pulled the plug on %s"
194 Note that %s is replaced with the identifier of the UPS in
196 question.
197 The message must be one element in the configuration file, so if it
199 contains spaces, you must wrap it in quotes.
200 NOTIFYMSG NOCOMM "Someone stole UPS %s"
202 Possible values for type:
204 ONLINE
206 UPS is back online
207 ONBATT
209 UPS is on battery
210 LOWBATT
212 UPS is on battery and has a low battery (is critical)
213 FSD
215 UPS is being shutdown by the primary (FSD = "Forced Shutdown")
216 COMMOK
218 Communications established with the UPS
219 COMMBAD
221 Communications lost to the UPS
222 SHUTDOWN
224 The system is being shutdown
225 REPLBATT
227 The UPS battery is bad and needs to be replaced
228 NOCOMM
230 A UPS is unavailable (can’t be contacted for monitoring)
231 NOTIFYFLAG type flag[+flag]...
233 By default, upsmon sends walls global messages to all logged in
234 users) via /bin/wall and writes to the syslog when things happen.
235 You can change this.
236 Examples:
238 NOTIFYFLAG ONLINE SYSLOG
240 NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
241 Possible values for the flags:
243 SYSLOG
245 Write the message to the syslog
246 WALL
248 Write the message to all users with /bin/wall
249 EXEC
251 Execute NOTIFYCMD (see above) with the message
252 IGNORE
254 Don’t do anything
255 If you use IGNORE, don’t use any other flags on the same line.
257 POLLFREQ seconds
259 Normally upsmon polls the upsd(8) server every 5 seconds. If this
260 is flooding your network with activity, you can make it higher. You
261 can also make it lower to get faster updates in some cases.
262 There are some catches. First, if you set the POLLFREQ too high,
264 you may miss short-lived power events entirely. You also risk
265 triggering the DEADTIME (see above) if you use a very large number.
266 Second, there is a point of diminishing returns if you set it too
268 low. While upsd normally has all of the data available to it
269 instantly, most drivers only refresh the UPS status once every 2
270 seconds. Polling any more than that usually doesn’t get you the
271 information any faster.
272 POLLFREQALERT seconds
274 This is the interval that upsmon waits between polls if any of its
275 UPSes are on battery. You can use this along with POLLFREQ above to
276 slow down polls during normal behavior, but get quicker updates
277 when something bad happens.
278 This should always be equal to or lower than the POLLFREQ value. By
280 default it is also set 5 seconds.
281 The warnings from the POLLFREQ entry about too-high and too-low
283 values also apply here.
284 POWERDOWNFLAG filename
286 upsmon creates this file when running in primary mode when the UPS
287 needs to be powered off. You should check for this file in your
288 shutdown scripts and call upsdrvctl shutdown if it exists.
289 This is done to forcibly reset the secondary systems, so they don’t
291 get stuck at the "halted" stage even if the power returns during
292 the shutdown process. This usually does not work well on
293 contact-closure UPSes that use the genericups driver.
294 See the config-notes.txt file in the docs subdirectory for more
296 information. Refer to the section:
297 "Configuring automatic shutdowns for low battery events", or refer
299 to the online version.
300 RBWARNTIME seconds
302 When a UPS says that it needs to have its battery replaced, upsmon
303 will generate a NOTIFY_REPLBATT event. By default, this happens
304 every 43200 seconds (12 hours).
305 If you need another value, set it here.
307 RUN_AS_USER username
309 upsmon normally runs the bulk of the monitoring duties under
310 another user ID after dropping root privileges. On most systems
311 this means it runs as "nobody", since that’s the default from
312 compile-time.
313 The catch is that "nobody" can’t read your upsmon.conf, since by
315 default it is installed so that only root can open it. This means
316 you won’t be able to reload the configuration file, since it will
317 be unavailable.
318 The solution is to create a new user just for upsmon, then make it
320 run as that user. I suggest "nutmon", but you can use anything that
321 isn’t already taken on your system. Just create a regular user with
322 no special privileges and an impossible password.
323 Then, tell upsmon to run as that user, and make upsmon.conf
325 readable by it. Your reloads will work, and your config file will
326 stay secure.
327 This file should not be writable by the upsmon user, as it would be
329 possible to exploit a hole, change the SHUTDOWNCMD to something
330 malicious, then wait for upsmon to be restarted.
331 SHUTDOWNCMD command
333 upsmon runs this command when the system needs to be brought down.
334 If it is a secondary, it will do that immediately whenever the
335 current overall power value drops below the MINSUPPLIES value
336 above.
337 When upsmon is a primary, it will allow any secondaries to log out
339 before starting the local shutdown procedure.
340 Note that the command needs to be one element in the config file.
342 If your shutdown command includes spaces, then put it in quotes to
343 keep it together, i.e.:
344 SHUTDOWNCMD "/sbin/shutdown -h +0"
346 CERTPATH certificate file or database
348 When compiled with SSL support, you can enter the certificate path
349 here.
350 With NSS:
352 Certificates are stored in a dedicated database (data split in
353 3 files). Specify the path of the database directory.
354 With OpenSSL:
356 Directory containing CA certificates in PEM format, used to
357 verify the server certificate presented by the upsd server. The
358 files each contain one CA certificate. The files are looked up
359 by the CA subject name hash value, which must hence be
360 available.
361 CERTIDENT certificate name database password
363 When compiled with SSL support with NSS, you can specify the
364 certificate name to retrieve from database to authenticate itself
365 and the password required to access certificate related private
366 key.
367 CERTHOST hostname certificate name certverify forcessl
369 When compiled with SSL support with NSS, you can specify security
370 directive for each server you can contact.
371 Each entry maps server name with the expected certificate name and
373 flags indicating if the server certificate is verified and if the
374 connection must be secure.
375 CERTVERIFY 0 | 1
377 When compiled with SSL support, make upsmon verify all connections
378 with certificates.
379 Without this, there is no guarantee that the upsd is the right
381 host. Enabling this greatly reduces the risk of man-in-the-middle
382 attacks. This effectively forces the use of SSL, so don’t use this
383 unless all of your upsd hosts are ready for SSL and have their
384 certificates in order.
385 When compiled with NSS support of SSL, can be overridden for host
387 specified with a CERTHOST directive.
388 FORCESSL 0 | 1
390 When compiled with SSL, specify that a secured connection must be
391 used to communicate with upsd.
392 If you don’t use CERTVERIFY 1, then this will at least make sure
394 that nobody can sniff your sessions without a large effort. Setting
395 this will make upsmon drop connections if the remote upsd doesn’t
396 support SSL, so don’t use it unless all of them have it running.
397 When compiled with NSS support of SSL, can be overridden for host
399 specified with a CERTHOST directive.
400 DEBUG_MIN INTEGER
402 Optionally specify a minimum debug level for upsmon daemon, e.g.
403 for troubleshooting a deployment, without impacting foreground or
404 background running mode directly. Command-line option -D can only
405 increase this verbosity level.
406 Note
408 if the running daemon receives a reload command, presence of
409 the DEBUG_MIN NUMBER value in the configuration file can be
410 used to tune debugging verbosity in the running service daemon
411 (it is recommended to comment it away or set the minimum to
412 explicit zero when done, to avoid huge journals and I/O system
413 abuse). Keep in mind that for this run-time tuning, the
414 DEBUG_MIN value present in reloaded configuration files is
415 applied instantly and overrides any previously set value, from
416 file or CLI options, regardless of older logging level being
417 higher or lower than the newly found number; a missing (or
418 commented away) value however does not change the previously
419 active logging verbosity.
420
422 upsmon(8), upsd(8), nutupsdrv(8).
423 Internet resources:
425 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
426Network UPS Tools 2.8.0 04/26/2022 UPSMON.CONF(5)