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 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 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 slave is greater than HOSTSYNC on the
53 master, the master will give up waiting for the slave to
54 disconnect.
55 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 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 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 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 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 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 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 Also see the section on "power values" in upsmon(8).
91 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 You must have at least one MONITOR directive in upsmon.conf.
99 system is a UPS identifier. It is in this form:
101 <upsname>[@<hostname>[:<port>]]
103 The default hostname is "localhost". Some examples:
105 · "su700@mybox" means a UPS called "su700" on a system called
107 "mybox". This is the normal form.
108 · "fenton@bigbox:5678" is a UPS called "fenton" on a system called
110 "bigbox" which runs upsd(8) on port "5678".
111 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 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 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 MONITOR myups@bigserver 1 monmaster blah master
127 Meanwhile, the upsd.users on bigserver would look like this:
129 [monmaster]
131 password = blah
132 upsmon master # (or slave)
133 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 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 NOTIFYCMD command
146 upsmon calls this to send messages when things happen.
147 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 If you need to use upssched(8), then you must make it your
153 NOTIFYCMD by listing it here.
154 Note that this is only called for NOTIFY events that have EXEC set
156 with NOTIFYFLAG. See NOTIFYFLAG below for more details.
157 Making this some sort of shell script might not be a bad idea. For
159 more information and ideas, see docs/scheduling.txt
160 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 NOTIFYCMD "/path/to/script --foo --bar"
166 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 NOTIFYMSG type message
174 upsmon comes with a set of stock messages for various events. You
175 can change them if you like.
176 NOTIFYMSG ONLINE "UPS %s is getting line power"
178 NOTIFYMSG ONBATT "Someone pulled the plug on %s"
180 Note that %s is replaced with the identifier of the UPS in
182 question.
183 The message must be one element in the configuration file, so if it
185 contains spaces, you must wrap it in quotes.
186 NOTIFYMSG NOCOMM "Someone stole UPS %s"
188 Possible values for type:
190 ONLINE
192 UPS is back online
193 ONBATT
195 UPS is on battery
196 LOWBATT
198 UPS is on battery and has a low battery (is critical)
199 FSD
201 UPS is being shutdown by the master (FSD = "Forced Shutdown")
202 COMMOK
204 Communications established with the UPS
205 COMMBAD
207 Communications lost to the UPS
208 SHUTDOWN
210 The system is being shutdown
211 REPLBATT
213 The UPS battery is bad and needs to be replaced
214 NOCOMM
216 A UPS is unavailable (can’t be contacted for monitoring)
217 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 Examples:
224 NOTIFYFLAG ONLINE SYSLOG
226 NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
227 Possible values for the flags:
229 SYSLOG
231 Write the message to the syslog
232 WALL
234 Write the message to all users with /bin/wall
235 EXEC
237 Execute NOTIFYCMD (see above) with the message
238 IGNORE
240 Don’t do anything
241 If you use IGNORE, don’t use any other flags on the same line.
243 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 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 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 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 This should always be equal to or lower than the POLLFREQ value. By
266 default it is also set 5 seconds.
267 The warnings from the POLLFREQ entry about too-high and too-low
269 values also apply here.
270 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 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 See the config-notes.txt file in the docs subdirectory for more
282 information. Refer to the section:
283 "Configuring automatic shutdowns for low battery events", or refer
285 to the online version.
286 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 If you need another value, set it here.
293 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 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 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 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 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 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 When upsmon is a master, it will allow any slaves to log out before
324 starting the local shutdown procedure.
325 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 SHUTDOWNCMD "/sbin/shutdown -h +0"
331 CERTPATH certificate file or database
333 When compiled with SSL support, you can enter the certificate path
334 here.
335 With NSS:
337 Certificates are stored in a dedicated database (splitted in 3
338 files). Specify the path of the database directory.
339 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 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 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 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 CERTVERIFY 0 | 1
362 When compiled with SSL support, make upsmon verify all connections
363 with certificates.
364 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 When compiled with NSS support of SSL, can be overriden for host
372 specified with a CERTHOST directive.
373 FORCESSL 0 | 1
375 When compiled with SSL, specify that a secured connection must be
376 used to communicate with upsd.
377 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 When compiled with NSS support of SSL, can be overriden for host
384 specified with a CERTHOST directive.
385
387 upsmon(8), upsd(8), nutupsdrv(8).
388 Internet resources:
390 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
391Network UPS Tools 2.7.3. 12/29/2015 UPSMON.CONF(5)