422 lines
15 KiB
Groff
422 lines
15 KiB
Groff
.TH UPSMON 8 "Mon Jan 22 2007" "" "Network UPS Tools (NUT)"
|
|
.SH NAME
|
|
upsmon \- UPS monitor and shutdown controller
|
|
.SH SYNOPSIS
|
|
.B upsmon \-h
|
|
|
|
.B upsmon \-c \fIcommand\fR
|
|
|
|
.B upsmon [\-D] [\-p] [\-u \fIuser\fR]
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.B upsmon
|
|
is the client process that is responsible for the most important part of
|
|
UPS monitoring \(hy shutting down the system when the power goes out. It
|
|
can call out to other helper programs for notification purposes during
|
|
power events.
|
|
|
|
upsmon can monitor multiple systems using a single process. Every UPS
|
|
that is defined in the \fBupsmon.conf\fR(5) configuration file is assigned
|
|
a power value and a type (slave or master).
|
|
|
|
.SH OPTIONS
|
|
|
|
.IP \-h
|
|
Display the help message.
|
|
|
|
.IP "\-c \fIcommand\fR"
|
|
Send the command \fIcommand\fR to the existing upsmon process. Valid
|
|
commands are:
|
|
|
|
fsd \(hy shutdown all master UPSes (use with caution)
|
|
|
|
stop \(hy stop monitoring and exit
|
|
|
|
reload \(hy reread \fBupsmon.conf\fR(5) configuration file. See
|
|
"reloading nuances" below if this doesn't work.
|
|
|
|
.IP \-D
|
|
Raise the debugging level. upsmon will run in the foreground and prints
|
|
information on stdout about the monitoring process. Use this multiple
|
|
times for more details.
|
|
|
|
.IP \-K
|
|
Test for the shutdown flag. If it exists and contains the magic string
|
|
from upsmon, then upsmon will exit with EXIT_SUCCESS. Any other condition
|
|
will make upsmon exit with EXIT_FAILURE.
|
|
|
|
You can test for a successful exit from upsmon \-K in your shutdown
|
|
scripts to know when to call \fBupsdrvctl\fR(8) to shut down the UPS.
|
|
|
|
.IP \-p
|
|
Run privileged all the time. Normally upsmon will split into two
|
|
processes. The majority of the code runs as an unprivileged user, and
|
|
only a tiny stub runs as root. This switch will disable that mode, and
|
|
run the old "all root all the time" system.
|
|
|
|
This is not the recommended mode, and you should not use this unless you
|
|
have a very good reason.
|
|
|
|
.IP "\-u \fIuser\fR"
|
|
Set the user for the unprivileged monitoring process. This has no effect
|
|
when using \-p.
|
|
.IP
|
|
The default user is set at configure time with 'configure
|
|
\-\-with\-user=...'. Typically this is 'nobody', but other distributions
|
|
will probably have a specific 'nut' user for this task. If your
|
|
notification scripts need to run as a specific user, set it here.
|
|
.IP
|
|
You can also set this in the \fBupsmon.conf\fR(5) file with the
|
|
RUN_AS_USER directive.
|
|
|
|
.SH UPS DEFINITIONS
|
|
|
|
In the \fBupsmon.conf\fR(5), you must specify at least one UPS that will
|
|
be monitored. Use the MONITOR directive.
|
|
|
|
MONITOR \fIsystem\fR \fIpowervalue\fR \fIusername\fR
|
|
\fIpassword\fR \fItype\fR
|
|
|
|
The \fIsystem\fR refers to a \fBupsd\fR(8) server, in the form
|
|
upsname[@hostname[:port]]. The default hostname is "localhost". Some
|
|
examples follow:
|
|
|
|
\(hy "su700@mybox" means a UPS called "su700" on a system called "mybox".
|
|
This is the normal form.
|
|
|
|
\(hy "fenton@bigbox:5678" is a UPS called "fenton" on a system called
|
|
"bigbox" which runs \fBupsd\fR(8) on port "5678".
|
|
|
|
The \fIpowervalue\fR refers to how many power supplies on this system are
|
|
being driven this UPS. This is typically set to 1, but see the section
|
|
on power values below.
|
|
|
|
The \fIusername\fR is a section in your \fBupsd.users\fR(5) file.
|
|
Whatever password you set in that section must match the \fIpassword\fR
|
|
set in this file.
|
|
|
|
The type set in that section must also match the \fItype\fR here \(hy
|
|
\fBmaster\fR or \fBslave\fR. In general, a master process is one
|
|
running on the system with the UPS actually plugged into a serial
|
|
port, and a slave is drawing power from the UPS but can't talk to it
|
|
directly. See the section on UPS types for more.
|
|
|
|
.SH NOTIFY EVENTS
|
|
|
|
upsmon senses several events as it monitors each UPS. They are called
|
|
notify events as they can be used to tell the users and admins about the
|
|
change in status. See the additional NOTIFY\(hyrelated sections below for
|
|
information on customizing the delivery of these messages.
|
|
|
|
.IP ONLINE
|
|
The UPS is back on line.
|
|
|
|
.IP ONBATT
|
|
The UPS is on battery.
|
|
|
|
.IP LOWBATT
|
|
The UPS battery is low (as determined by the driver).
|
|
|
|
.IP FSD
|
|
The UPS has been commanded into the "forced shutdown" mode.
|
|
|
|
.IP COMMOK
|
|
Communication with the UPS has been established.
|
|
|
|
.IP COMMBAD
|
|
Communication with the UPS was just lost.
|
|
|
|
.IP SHUTDOWN
|
|
The local system is being shut down.
|
|
|
|
.IP REPLBATT
|
|
The UPS needs to have its battery replaced.
|
|
|
|
.IP NOCOMM
|
|
The UPS can't be contacted for monitoring.
|
|
|
|
.SH NOTIFY COMMAND
|
|
|
|
In \fBupsmon.conf\fR(5), you can configure a program called the NOTIFYCMD
|
|
that will handle events that occur.
|
|
|
|
NOTIFYCMD "\fIpath to program\fR"
|
|
|
|
NOTIFYCMD "/usr/local/bin/notifyme"
|
|
|
|
Remember to wrap the path in "quotes" if it contains any spaces.
|
|
|
|
The program you run as your NOTIFYCMD can use the environment variables
|
|
NOTIFYTYPE and UPSNAME to know what has happened and on which UPS. It
|
|
also receives the notification message (see below) as the first (and
|
|
only) argument, so you can deliver a preformatted message too.
|
|
|
|
Note that the NOTIFYCMD will only be called for a given event when you set
|
|
the EXEC flag by using the notify flags, below:
|
|
|
|
.SH NOTIFY FLAGS
|
|
|
|
By default, all notify events (see above) generate a global message
|
|
(wall) to all users, plus they are logged via the syslog. You can change
|
|
this with the NOTIFYFLAG directive in the configuration file:
|
|
|
|
NOTIFYFLAG \fInotifytype\fR \fIflags\fR
|
|
|
|
Examples:
|
|
|
|
NOTIFYFLAG ONLINE SYSLOG
|
|
|
|
NOTIFYFLAG ONBATT SYSLOG+WALL
|
|
|
|
NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC
|
|
|
|
The flags that can be set on a given notify event are:
|
|
|
|
.IP SYSLOG
|
|
Write this message to the syslog.
|
|
|
|
.IP WALL
|
|
Send this message to all users on the system via 'wall'.
|
|
|
|
.IP EXEC
|
|
Execute the NOTIFYCMD.
|
|
|
|
.IP IGNORE
|
|
Don't do anything. If you use this, don't use any of the other flags.
|
|
.P
|
|
You can mix these flags. "SYSLOG+WALL+EXEC" does all three for a given
|
|
event.
|
|
|
|
.SH NOTIFY MESSAGES
|
|
|
|
upsmon comes with default messages for each of the NOTIFY events. These
|
|
can be changed with the NOTIFYMSG directive.
|
|
|
|
NOTIFYMSG \fItype\fR "\fImessage\fR"
|
|
|
|
Examples:
|
|
|
|
NOTIFYMSG ONLINE "UPS %s is getting line power"
|
|
|
|
NOTIFYMSG ONBATT "Someone pulled the plug on %s"
|
|
|
|
The first instance of %s is replaced with the identifier of the UPS that
|
|
generated the event. These messages are used when sending walls to the
|
|
users directly from upsmon, and are also passed to the NOTIFYCMD.
|
|
|
|
.SH POWER VALUES
|
|
|
|
The "current overall power value" is the sum of all UPSes that are
|
|
currently able to supply power to the system hosting upsmon. Any
|
|
UPS that is either on line or just on battery contributes to this
|
|
number. If a UPS is critical (on battery and low battery) or has been
|
|
put into "forced shutdown" mode, it no longer contributes.
|
|
|
|
A "power value" on a MONITOR line in the config file is the number of
|
|
power supplies that the UPS runs on the current system.
|
|
|
|
MONITOR \fIupsname\fR \fIpowervalue\fR \fIusername\fR \fIpassword\fR \fItype\fR
|
|
|
|
Normally, you only have one power supply, so it will be set to 1.
|
|
|
|
MONITOR myups@myhost 1 username mypassword master
|
|
|
|
On a large server with redundant power supplies, the power value for a UPS
|
|
may be greater than 1. You may also have more than one of them defined.
|
|
|
|
MONITOR ups\-alpha@myhost 2 username mypassword master
|
|
|
|
MONITOR ups\-beta@myhost 2 username mypassword master
|
|
|
|
You can also set the power value for a UPS to 0 if it does not supply any
|
|
power to that system. This is generally used when you want to use the
|
|
upsmon notification features for a UPS even though it's not actually
|
|
running the system that hosts upsmon. Don't set this to "master" unless
|
|
you really want to power this UPS off when this instance of upsmon needs
|
|
to shut down for its own reasons.
|
|
|
|
MONITOR faraway@anotherbox 0 username mypassword slave
|
|
|
|
The "minimum power value" is the number of power supplies that must be
|
|
receiving power in order to keep the computer running.
|
|
|
|
MINSUPPLIES \fIvalue\fR
|
|
|
|
Typical PCs only have 1, so most users will leave this at the default.
|
|
|
|
MINSUPPLIES 1
|
|
|
|
If you have a server or similar system with redundant power, then this
|
|
value will usually be set higher. One that requires three power supplies
|
|
to be running at all times would simply set it to 3.
|
|
|
|
MINSUPPLIES 3
|
|
|
|
When the current overall power value drops below the minimum power value,
|
|
upsmon starts the shutdown sequence. This design allows you to lose some
|
|
of your power supplies in a redundant power environment without bringing
|
|
down the entire system while still working properly for smaller systems.
|
|
|
|
.SH UPS TYPES
|
|
|
|
upsmon and \fBupsd\fR(8) don't always run on the same system. When they
|
|
do, any UPSes that are directly attached to the upsmon host should be
|
|
monitored in "master" mode. This makes upsmon take charge of that
|
|
equipment, and it will wait for slaves to disconnect before shutting
|
|
down the local system. This allows the distant systems (monitoring over
|
|
the network) to shut down cleanly before \fBupsdrvctl shutdown\fR runs
|
|
and turns them all off.
|
|
|
|
When upsmon runs as a slave, it is relying on the distant system to tell
|
|
it about the state of the UPS. When that UPS goes critical (on battery
|
|
and low battery), it immediately invokes the local shutdown command. This
|
|
needs to happen quickly. Once it disconnects from the distant
|
|
\fBupsd\fR(8) server, the master upsmon will start its own shutdown
|
|
process. Your slaves must all shut down before the master turns off the
|
|
power or filesystem damage may result.
|
|
|
|
upsmon deals with slaves that get wedged, hang, or otherwise fail to
|
|
disconnect from \fBupsd\fR(8) in a timely manner with the HOSTSYNC
|
|
timer. During a shutdown situation, the master upsmon will give up after
|
|
this interval and it will shut down anyway. This keeps the master from
|
|
sitting there forever (which would endanger that host) if a slave should
|
|
break somehow. This defaults to 15 seconds.
|
|
|
|
If your master system is shutting down too quickly, set the FINALDELAY
|
|
interval to something greater than the default 15 seconds. Don't set
|
|
this too high, or your UPS battery may run out of power before the
|
|
master upsmon process shuts down that system.
|
|
|
|
.SH TIMED SHUTDOWNS
|
|
|
|
For those rare situations where the shutdown process can't be completed
|
|
between the time that low battery is signalled and the UPS actually powers
|
|
off the load, use the \fBupssched\fR(8) helper program. You can use it
|
|
along with upsmon to schedule a shutdown based on the "on battery" event.
|
|
upssched can then come back to upsmon to initiate the shutdown once it's
|
|
run on battery too long.
|
|
|
|
This can be complicated and messy, so stick to the default critical UPS
|
|
handling if you can.
|
|
|
|
.SH REDUNDANT POWER SUPPLIES
|
|
|
|
If you have more than one power supply for redundant power, you may also
|
|
have more than one UPS feeding your computer. upsmon can handle this. Be
|
|
sure to set the UPS power values appropriately and the MINSUPPLIES value
|
|
high enough so that it keeps running until it really does need to shut
|
|
down.
|
|
|
|
For example, the HP NetServer LH4 by default has 3 power supplies
|
|
installed, with one bay empty. It has two power cords, one per side of
|
|
the box. This means that one power cord powers two power supply bays,
|
|
and that you can only have two UPSes supplying power.
|
|
|
|
Connect UPS "alpha" to the cord feeding two power supplies, and UPS
|
|
"beta" to the cord that feeds the third and the empty slot. Define alpha
|
|
as a powervalue of 2, and beta as a powervalue of 1. Set the MINSUPPLIES
|
|
to 2.
|
|
|
|
When alpha goes on battery, your current overall power value will stay
|
|
at 3, as it's still supplying power. However, once it goes critical (on
|
|
battery and low battery), it will stop contributing to the current overall
|
|
power value. That means the value will be 1 (beta alone), which is less
|
|
than 2. That is insufficient to run the system, and upsmon will invoke
|
|
the shutdown sequence.
|
|
|
|
However, if beta goes critical, subtracting its contribution will take the
|
|
current overall value from 3 to 2. This is just high enough to satisfy
|
|
the minimum, so the system will continue running as before. If beta
|
|
returns later, it will be re\(hyadded and the current value will go back to
|
|
3. This allows you to swap out UPSes, change a power configuration, or
|
|
whatever, as long as you maintain the minimum power value at all times.
|
|
|
|
.SH MIXED OPERATIONS
|
|
|
|
Besides being able to monitor multiple UPSes, upsmon can also monitor them
|
|
as different roles. If you have a system with multiple power supplies
|
|
serviced by separate UPS batteries, it's possible to be a master on one
|
|
and a slave on the other. This usually happens when you run out of serial
|
|
ports and need to do the monitoring through another system nearby.
|
|
|
|
This is also complicated, especially when it comes time to power down a
|
|
UPS that has gone critical but doesn't supply the local system. You can
|
|
do this with some scripting magic in your notify command script, but it's
|
|
beyond the scope of this manual.
|
|
|
|
.SH FORCED SHUTDOWNS
|
|
|
|
When upsmon is forced to bring down the local system, it sets the
|
|
"FSD" (forced shutdown) flag on any UPSes that it is running in master
|
|
mode. This is used to synchronize slaves in the event that a master UPS
|
|
that is otherwise OK needs to be brought down due to some pressing event
|
|
on the master.
|
|
|
|
You can manually invoke this mode on the master upsmon by starting another
|
|
copy with '\-c fsd'. This is useful when you want to initiate a shutdown
|
|
before the critical stage through some external means, such as
|
|
\fBupssched\fR(8).
|
|
|
|
.SH DEAD UPSES
|
|
|
|
In the event that upsmon can't reach \fBupsd\fR(8), it declares that UPS
|
|
"dead" after some interval controlled by DEADTIME in the
|
|
\fBupsmon.conf\fR(5). If this happens while that UPS was last known to be
|
|
on battery, it is assumed to have gone critical and no longer contributes
|
|
to the overall power value.
|
|
|
|
upsmon will alert you to a UPS that can't be contacted for monitoring
|
|
with a "NOCOMM" notifier by default every 300 seconds. This can be
|
|
changed with the NOCOMMWARNTIME setting.
|
|
|
|
.SH RELOADING NUANCES
|
|
|
|
upsmon usually gives up root powers for the process that does most of
|
|
the work, including handling signals like SIGHUP to reload the configuration
|
|
file. This means your \fBupsmon.conf\fR(8) file must be readable by
|
|
the non\(hyroot account that upsmon switches to.
|
|
|
|
If you want reloads to work, upsmon must run as some user that has
|
|
permissions to read the configuration file. I recommend making a new
|
|
user just for this purpose, as making the file readable by "nobody"
|
|
(the default user) would be a bad idea.
|
|
|
|
See the RUN_AS_USER section in \fBupsmon.conf\fR(8) for more on this topic.
|
|
|
|
Additionally, you can't change the SHUTDOWNCMD or POWERDOWNFLAG
|
|
definitions with a reload due to the split\(hyprocess model. If you change
|
|
those values, you \fBmust\fR stop upsmon and start it back up. upsmon
|
|
will warn you in the syslog if you make changes to either of those
|
|
values during a reload.
|
|
|
|
.SH SIMULATING POWER FAILURES
|
|
|
|
To test a synchronized shutdown without pulling the plug on your UPS(es),
|
|
you need only set the forced shutdown (FSD) flag on them. You can do this
|
|
by calling upsmon again to set the flag \(hy i.e.:
|
|
|
|
upsmon \-c fsd
|
|
|
|
After that, the master and the slaves will do their usual shutdown sequence
|
|
as if the battery had gone critical. This is much easier on your UPS
|
|
equipment, and it beats crawling under a desk to find the plug.
|
|
|
|
.SH FILES
|
|
|
|
\fBupsmon.conf\fR(5)
|
|
|
|
.SH SEE ALSO
|
|
|
|
.SS Server:
|
|
\fBupsd\fR(8)
|
|
|
|
.SS Clients:
|
|
\fBupsc\fR(8), \fBupscmd\fR(8),
|
|
\fBupsrw\fR(8), \fBupsmon\fR(8)
|
|
|
|
.SS CGI programs:
|
|
\fBupsset.cgi\fR(8), \fBupsstats.cgi\fR(8), \fBupsimage.cgi\fR(8)
|
|
|
|
.SS Internet resources:
|
|
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
|