1
.TH UPSMON.CONF 5 "Mon Jan 22 2007" "" "Network UPS Tools (NUT)"
3
upsmon.conf \- Configuration for Network UPS Tools upsmon
7
This file's primary job is to define the systems that \fBupsmon\fR(8)
8
will monitor and to tell it how to shut down the system when necessary.
9
It will contain passwords, so keep it secure. Ideally,only the upsmon
10
process should be able to read it.
12
Additionally, other optional configuration values can be set in this
15
.SH CONFIGURATION DIRECTIVES
17
.IP "DEADTIME \fIseconds\fR"
19
upsmon allows a UPS to go missing for this many seconds before declaring
20
it "dead". The default is 15 seconds.
22
upsmon requires a UPS to provide status information every few seconds
23
(see POLLFREQ and POLLFREQALERT) to keep things updated. If the status
24
fetch fails, the UPS is marked stale. If it stays stale for more than
25
DEADTIME seconds, the UPS is marked dead.
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 is
29
providing a critical amount of power to your system. This seems
30
disruptive, but the alternative is barreling ahead into oblivion and
31
crashing when you run out of power.
33
Note: DEADTIME should be a multiple of POLLFREQ and POLLFREQALERT.
34
Otherwise, you'll have "dead" UPSes simply because upsmon isn't polling
35
them quickly enough. Rule of thumb: take the larger of the two POLLFREQ
36
values, and multiply by 3.
38
.IP "FINALDELAY \fIseconds\fR"
40
When running in master mode, upsmon waits this long after sending the
41
NOTIFY_SHUTDOWN to warn the users. After the timer elapses, it then
42
runs your SHUTDOWNCMD. By default this is set to 5 seconds.
44
If you need to let your users do something in between those events,
45
increase this number. Remember, at this point your UPS battery is
46
almost depleted, so don't make this too big.
48
Alternatively, you can set this very low so you don't wait around when
49
it's time to shut down. Some UPSes don't give much warning for low
50
battery and will require a value of 0 here for a safe shutdown.
52
Note: If FINALDELAY on the slave is greater than HOSTSYNC on the master,
53
the master will give up waiting for the slave to disconnect.
55
.IP "HOSTSYNC \fIseconds\fR"
57
upsmon will wait up to this many seconds in master mode for the slaves
58
to disconnect during a shutdown situation. By default, this is 15
61
When a UPS goes critical (on battery + low battery, or "FSD" \(hy forced
62
shutdown), the slaves are supposed to disconnect and shut down right
63
away. The HOSTSYNC timer keeps the master upsmon from sitting there
64
forever if one of the slaves gets stuck.
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 the
69
FSD flag. If that timer expires, the slave will assume that the master
70
is broken and will shut down anyway.
72
This keeps the slaves from shutting down during a short\(hylived status
73
change to "OB LB" that the slaves see but the master misses.
75
.IP "MINSUPPLIES \fInum\fR"
77
Set the number of power supplies that must be receiving power to keep
78
this system running. Normal computers have just one power supply, so
79
the default value of 1 is acceptable.
81
Large/expensive server type systems usually have more, and can run
82
with a few missing. The HP NetServer LH4 can run with 2 out of 4, for
83
example, so you'd set it to 2. The idea is to keep the box running
84
as long as possible, right?
86
Obviously you have to put the redundant supplies on different UPS
87
circuits for this to make sense! See big\(hyservers.txt in the docs
88
subdirectory for more information and ideas on how to use this
91
Also see the section on "power values" in \fBupsmon\fR(8).
93
.IP "MONITOR \fIsystem\fR \fIpowervalue\fR \fIusername\fR \fIpassword\fR \fItype\fR"
95
Each UPS that you need to be monitor should have a MONITOR line. Not
96
all of these need supply power to the system that is running upsmon.
97
You may monitor other systems if you want to be able to send
98
notifications about status changes on them.
100
You must have at least one MONITOR directive in this file.
102
\fIsystem\fR is a UPS identifier. It is in this form:
104
<upsname>[@<hostname>[:<port>]]
106
The default hostname is "localhost". Some examples:
108
\(hy "su700@mybox" means a UPS called "su700" on a system called "mybox".
109
This is the normal form.
111
\(hy "fenton@bigbox:5678" is a UPS called "fenton" on a system called
112
"bigbox" which runs \fBupsd\fR(8) on port "5678".
114
\fIpowervalue\fR is an integer representing the number of power supplies
115
that the UPS feeds on this system. Most normal computers have one power
116
supply, and the UPS feeds it, so this value will be 1. You need a very
117
large or special system to have anything higher here.
119
You can set the \fIpowervalue\fR to 0 if you want to monitor a UPS that
120
doesn't actually supply power to this system. This is useful when you
121
want to have upsmon do notifications about status changes on a UPS
122
without shutting down when it goes critical.
124
The \fIusername\fR and \fIpassword\fR on this line must match an entry
125
in that system's \fBupsd.users\fR(5). If your username is "monmaster"
126
and your password is "blah", the MONITOR line might look like this:
128
MONITOR myups@bigserver 1 monmaster blah master
130
Meanwhile, the upsd.users on 'bigserver' would look like this:
136
allowfrom = (ACLs from \fBupsd.conf\fR(5))
138
upsmon master (or slave)
140
The \fItype\fR refers to the relationship with \fBupsd\fR(8). It can
141
be either "master" or "slave". See \fBupsmon\fR(8) for more information
142
on the meaning of these modes. The mode you pick here also goes in
143
the upsd.users file, as seen in the example above.
145
.IP "NOCOMMWARNTIME \fIseconds\fR"
147
upsmon will trigger a NOTIFY_NOCOMM after this many seconds if it can't
148
reach any of the UPS entries in this configuration file. It keeps
149
warning you until the situation is fixed. By default this is 300
152
.IP "NOTIFYCMD \fIcommand\fR"
154
upsmon calls this to send messages when things happen.
156
This command is called with the full text of the message as one
157
argument. The environment string NOTIFYTYPE will contain the type
158
string of whatever caused this event to happen.
160
If you need to use \fBupssched\fR(8), then you must make it your
161
NOTIFYCMD by listing it here.
163
Note that this is only called for NOTIFY events that have EXEC set with
164
NOTIFYFLAG. See NOTIFYFLAG below for more details.
166
Making this some sort of shell script might not be a bad idea. For
167
more information and ideas, see pager.txt in the docs directory.
169
Remember, this also needs to be one element in the configuration file,
170
so if your command has spaces, then wrap it in quotes.
172
NOTIFYCMD "/path/to/script \-\-foo \-\-bar"
174
This script is run in the background \(hy that is, upsmon forks before it
175
calls out to start it. This means that your NOTIFYCMD may have multiple
176
instances running simultaneously if a lot of stuff happens all at once.
177
Keep this in mind when designing complicated notifiers.
179
.IP "NOTIFYMSG \fItype\fR \fImessage\fR\"
181
upsmon comes with a set of stock messages for various events. You can
182
change them if you like.
184
NOTIFYMSG ONLINE "UPS %s is getting line power"
186
NOTIFYMSG ONBATT "Someone pulled the plug on %s"
188
Note that %s is replaced with the identifier of the UPS in question.
190
Possible values for \fItype\fR:
192
ONLINE \(hy UPS is back online
194
ONBATT \(hy UPS is on battery
196
LOWBATT \(hy UPS is on battery and has a low battery (is critical)
198
FSD \(hy UPS is being shutdown by the master (FSD = "Forced Shutdown")
200
COMMOK \(hy Communications established with the UPS
202
COMMBAD \(hy Communications lost to the UPS
204
SHUTDOWN \(hy The system is being shutdown
206
REPLBATT \(hy The UPS battery is bad and needs to be replaced
208
NOCOMM \(hy A UPS is unavailable (can't be contacted for monitoring)
210
The message must be one element in the configuration file, so if it
211
contains spaces, you must wrap it in quotes.
213
NOTIFYMSG NOCOMM "Someone stole UPS %s"
215
.IP "NOTIFYFLAG \fItype\fR \fIflag\fR[+\fIflag\fR][+\fIflag\fR]..."
217
By default, upsmon sends walls global messages to all logged in users)
218
via /bin/wall and writes to the syslog when things happen. You can
223
NOTIFYFLAG ONLINE SYSLOG
225
NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
227
Possible values for the flags:
229
SYSLOG \(hy Write the message to the syslog
231
WALL \(hy Write the message to all users with /bin/wall
233
EXEC \(hy Execute NOTIFYCMD (see above) with the message
235
IGNORE \(hy Don't do anything
237
If you use IGNORE, don't use any other flags on the same line.
239
.IP "POLLFREQ \fIseconds\fR"
241
Normally upsmon polls the \fBupsd\fR(8) server every 5 seconds. If this
242
is flooding your network with activity, you can make it higher. You can
243
also make it lower to get faster updates in some cases.
245
There are some catches. First, if you set the POLLFREQ too high, you
246
may miss short\(hylived power events entirely. You also risk triggering
247
the DEADTIME (see above) if you use a very large number.
249
Second, there is a point of diminishing returns if you set it too low.
250
While upsd normally has all of the data available to it instantly, most
251
drivers only refresh the UPS status once every 2 seconds. Polling any
252
more than that usually doesn't get you the information any faster.
254
.IP "POLLFREQALERT \fIseconds\fR"
256
This is the interval that upsmon waits between polls if any of its UPSes
257
are on battery. You can use this along with POLLFREQ above to slow down
258
polls during normal behavior, but get quicker updates when something bad
261
This should always be equal to or lower than the POLLFREQ value. By
262
default it is also set 5 seconds.
264
The warnings from the POLLFREQ entry about too\(hyhigh and too\(hylow values
267
.IP "POWERDOWNFLAG \fIfilename\fR"
269
upsmon creates this file when running in master mode when the UPS needs
270
to be powered off. You should check for this file in your shutdown
271
scripts and call \fBupsdrvctl shutdown\fR if it exists.
273
This is done to forcibly reset the slaves, so they don't get stuck at
274
the "halted" stage even if the power returns during the shutdown
275
process. This usually does not work well on contact\(hyclosure UPSes that
276
use the genericups driver.
278
See the shutdown.txt file in the docs subdirectory for more information.
280
.IP "RBWARNTIME \fIseconds\fR"
282
When a UPS says that it needs to have its battery replaced, upsmon will
283
generate a NOTIFY_REPLBATT event. By default this happens every 43200
284
seconds \(hy 12 hours.
286
If you need another value, set it here.
288
.IP "RUN_AS_USER \fIusername\fR"
290
upsmon normally runs the bulk of the monitoring duties under another user
291
ID after dropping root privileges. On most systems this means it runs
292
as "nobody", since that's the default from compile\(hytime.
294
The catch is that "nobody" can't read your upsmon.conf, since by default
295
it is installed so that only root can open it. This means you won't be
296
able to reload the configuration file, since it will be unavailable.
298
The solution is to create a new user just for upsmon, then make it run
299
as that user. I suggest "nutmon", but you can use anything that isn't
300
already taken on your system. Just create a regular user with no special
301
privileges and an impossible password.
303
Then, tell upsmon to run as that user, and make upsmon.conf readable by it.
304
Your reloads will work, and your config file will stay secure.
306
This file should not be writable by the upsmon user, as it would be
307
possible to exploit a hole, change the SHUTDOWNCMD to something
308
malicious, then wait for upsmon to be restarted.
310
.IP "SHUTDOWNCMD \fIcommand\fR"
312
upsmon runs this command when the system needs to be brought down. If
313
it is a slave, it will do that immediately whenever the current overall
314
power value drops below the MINSUPPLIES value above.
316
When upsmon is a master, it will allow any slaves to log out before
317
starting the local shutdown procedure.
319
Note that the command needs to be one element in the config file. If
320
your shutdown command includes spaces, then put it in quotes to keep it
323
SHUTDOWNCMD "/sbin/shutdown \-h +0"
326
\fBupsmon\fR(8), \fBupsd\fR(8), \fBnutupsdrv\fR(8).
328
.SS Internet resources:
329
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/