UPSMON(8) Network UPS Tools (NUT) UPSMON(8)NAMEupsmon - UPS monitor and shutdown controller
SYNOPSISupsmon-h
upsmon-c command
upsmon [-d] [-i] [-p] [-u user]
DESCRIPTIONupsmon is the client process that is responsible for the
most important part of UPS monitoring - 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 pro-
cess. Every UPS that is defined in the upsmon.conf(5)
configuration file is assigned a power value and a type
(slave or master).
OPTIONS-h Display the help message.
-c command
Send the command command to the existing upsmon
process. Valid commands are:
fsd - shutdown all master UPSes (use with caution)
stop - stop monitoring and exit
reload - reread upsmon.conf(5) configuration file.
See "reloading nuances" below if this doesn't work.
-d Enable debugging mode. upsmon runs in the fore-
ground and prints debugging information on stdout
about the monitoring process.
-i Enable infinite loop at shutdown. upsmon will keep
a process running after calling the shutdown com-
mand rather than exiting. This is only useful if
you have shutdown scripts that complain when upsmon
isn't running as they kill various processes.
-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.
-u user
Set the user for the unprivileged monitoring pro-
cess. This has no effect when using -p.
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.
You can also set this in the upsmon.conf(5) file
with the RUN_AS_USER directive.
UPS DEFINITIONS
In the upsmon.conf(5), you must specify at least one UPS
that will be monitored. Use the MONITOR directive.
MONITOR system powervalue username password type
The system refers to a upsd(8) server, in the form
[<upsname>@]hostname[:port]. The simplest form is just a
hostname, i.e.:
"localhost" refers to the first UPS on the local sys-
tem.
Other possibilities include:
"su700@mybox" means a UPS called "su700" on a system
called "mybox".
"elvis:1234" means the first UPS on a system called
"elvis", port 1234.
Finally, to use all of these options:
"fenton@bigbox:5678" is a UPS called "fenton" on a
system called "bigbox" which runs upsd(8) on port "5678".
Phew!
The powervalue 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 username is a section in your upsd.users(5) file.
Whatever password you set in that section must match the
password set in this file.
The type set in that section must also match the type here
- master or slave. 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.
NOTIFY EVENTSupsmon 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-related sections below for information
on customizing the delivery of these messages.
ONLINE The UPS is back on line.
ONBATT The UPS is on battery.
LOWBATT
The UPS battery is low (as determined by the
driver).
FSD The UPS has been commanded into the "forced shut-
down" mode.
COMMOK Communication with the UPS has been established.
COMMBAD
Communication with the UPS was just lost.
SHUTDOWN
The local system is being shut down.
REPLBATT
The UPS needs to have its battery replaced.
NOCOMM The UPS can't be contacted for monitoring.
NOTIFY COMMAND
In upsmon.conf(5), you can configure a program called the
NOTIFYCMD that will handle events that occur.
NOTIFYCMD "path to program"
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 environ-
ment variables NOTIFYTYPE and UPSNAME to know what has
happened and on which UPS. It also receives the notifica-
tion 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:
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 notifytype flags
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:
SYSLOG Write this message to the syslog.
WALL Send this message to all users on the system via
'wall'.
EXEC Execute the NOTIFYCMD.
IGNORE Don't do anything. If you use this, don't use any
of the other flags.
You can mix these flags. "SYSLOG+WALL+EXEC" does all
three for a given event.
NOTIFY MESSAGESupsmon comes with default messages for each of the NOTIFY
events. These can be changed with the NOTIFYMSG direc-
tive.
NOTIFYMSG type "message"
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.
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 cur-
rent system.
MONITOR upsname powervalue username password type
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 value
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 mini-
mum 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.
UPS TYPESupsmon and upsd(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 upsdrvctl
shutdown 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 immedi-
ately invokes the local shutdown command. This needs to
happen quickly. Once it disconnects from the distant
upsd(8) server, the master upsmon will start its own shut-
down 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 other-
wise fail to disconnect from upsd(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 pro-
cess shuts down that system.
TIMED SHUTDOWNS
For those rare situations where the shutdown process can't
be completed between the time that low battery is sig-
nalled and the UPS actually powers off the load, use the
upssched(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.
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 sup-
plies, 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. How-
ever, 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 contribu-
tion 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-added 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.
MIXED OPERATIONS
Besides being able to monitor multiple UPSes, upsmon can
also monitor them as different roles. If you have a sys-
tem 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.
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 upssched(8).
DEAD UPSES
In the event that upsmon can't reach upsd(8), it declares
that UPS "dead" after some interval controlled by DEADTIME
in the upsmon.conf(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 set-
ting.
RELOADING NUANCESupsmon 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
upsmon.conf(8) file must be readable by the non-root
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 mak-
ing the file readable by "nobody" (the default user) would
be a bad idea.
See the RUN_AS_USER section in upsmon.conf(8) for more on
this topic.
Additionally, you can't change the SHUTDOWNCMD or POWER-
DOWNFLAG definitions with a reload due to the split-pro-
cess model. If you change those values, you must stop
upsmon and start it back up. upsmon will warn you in the
syslog if you make changes to either of those values dur-
ing a reload.
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 - 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.
FILESupsmon.conf(5)SEE ALSO
Server:
upsd(8)
Clients:
upsc(8), upscmd(8), upsrw(8), upsmon(8)
CGI programs:
upsset.cgi(8), upsstats.cgi(8), upsimage.cgi(8)
Internet resources:
The NUT (Network UPS Tools) home page:
http://www.exploits.org/nut/
NUT mailing list archives and information:
http://lists.exploits.org/
Tue Oct 15 2002 UPSMON(8)
