Provided by: powstatd_1.5.1-9.1_amd64 
NAME
powstatd - a configurable UPS monitor.
SYNOPSIS
powstatd [ -t | -k ]
DESCRIPTION
powstatd is a configurable UPS monitoring daemon designed to work with SysVinit (e.g.,
most Linux distributions).
powstatd monitors a serial connection from a "dumb" or "relay" UPS for power failures and
shuts the machine down gracefully if the power remains off for more than a prespecified
interval. powstatd can also be configured to allow a master machine to control several
slave machines connected to the same UPS via a network connection. This allows you to run
several machines off the same UPS, with only one of the machines actually reading the UPS
status over the serial line. When compiled with appropriate options enabled, powstatd
also provides security by means of fast encryption of master/slave communication to
prevent malicious shutdown of slave systems.
powstatd has two options:
-t Test mode. Used to explore what a given UPS signals under various failure modes as
an aid to constructing an appropriate configuration file. When operating in test
mode, powstatd doesn't actually signal init, so while changes in UPS status are
detected, they are not acted upon. See configuration information for more details.
-k Kill mode. Directs powstatd to attempt to shut down the UPS. Most UPS systems
will ignore the shutdown signal unless the power is actually off. By shutting down
the UPS, powstatd ensures that once the main power returns the UPS will
automatically turn on and cause the machine to reboot.
CAVEATS
powstatd uses the connectionless UDP protocol to communicate UPS status from master to
slave. To keep just anyone from generating a UDP packet that will shut your slave machine
down when encrypted master/slave communication is not in use, the slave checks the IP
address of origin in the UDP packet it receives. If your master has more than one network
card, a master with multiple addresses may provide an unexpected IP address, which results
in the slave ignoring (legitimate) status reports.
So when you have a machine with multiple network cards, you must either ensure that the
master has a unique IP address (try connecting the single-NIC slave to the UPS and
demoting the dual-NIC master to slave instead), or use encrypted master/slave
communication, which does not need to check IP source addresses thanks to the
cryptographic measures used.
When using encrypted master/slave communication, powstatd also uses a timestamp to foil
replay attacks. Outdated status messages (as defined by a compile-time constant) are
simply rejected; thus master and slave clocks should be reasonably synchronized (using,
for example, the NTP protocol) or valid status messages may be rejected.
CONFIGURATION
powstatd is configured via a configuration file, /etc/powstatd.conf by default, that
specifies the serial line behavior of the UPS under its various failure modes (note that,
if compiled with appropriate security option enabled, powstatd will require that file
permissions on the configuration file deny rwx access to "group" or "other").
To configure your UPS, follow these steps:
0. Edit the Makefile to suit your installation. In particular, the secure master/slave
communication protocol is selected/deselected by making the appropriate change to the
definition of CFLGS in the Makefile. Note that users outside the United States wishing to
use the secure communication protocol will first need to download the public-domain ANSI C
implementation of TEA, the Tiny Encryption Algorithm, from
ftp://vader.eeng.brad.ac.uk/pub/crypto/xtea.c
1. Compile powstatd:
% make
or, if you are compiling on a DEC Alpha platform:
% make alpha
2. Make sure your new UPS is completely charged and is connected to your machine via the
serial monitoring line provided by the UPS manufacturer to your machine (if you did not
get such a monitoring line with your UPS, see the the UPS-HOWTO for information on how to
make one).
3. In order to configure powstatd, make sure your machine is not powered from the UPS but
is instead plugged directly into the wall outlet (your UPS should still, however, be
connected to the machine via the serial monitoring line). Instead, plug a desk light or
radio into the UPS.
4. Determine what serial line is connected to your UPS and create an initial copy of
/etc/powstatd.conf (you can look at the sample powstatd.conf.* files included in the
distribution) containing a single line specifying the serial line, e.g.:
watch ttyS0
5. As root, run powstatd in test mode (you'll have to be root to have rw access to
/dev/ttyS0 or whatever device corresponds to your UPS monitoring line).
% ./powstatd -t
Hit ^C to stop after you see something like:
CTS DSR DCD RNG RxD TxD DTR RTS STATUS
1 0 1 1 0 0 0 1 OK
1 0 1 1 0 0 0 1 OK
1 0 1 1 0 0 0 1 OK
1 0 1 1 0 0 0 1 OK
The output describes the state of the serial connection between the UPS and the computer.
Since the signaling needs of a UPS/computer connection are really quite low (just a few
bits), we aren't really using the serial connection as it was designed to be used for
higher-throughput applications. Instead, we'll use the individual control and transmission
lines in the nine wire standard connector a bit differently.
Of the nine wires, six are of particular interest: four "input" control lines (CTS, DSR,
DCD, RNG) and two "output" control lines (DTR, RTS). The remaining three lines consist of
an electrical ground and the two transmission lines (TxD and RxD, one running in each
direction); the latter are typically used for asynchronous serial information rather than
for control. Most "dumb" UPS systems ignore the transmission lines and operate only by
toggling combinations of the four "input" wires to indicate the status of the UPS and the
two "output" wires to send commands back to the UPS from the computer (for now, we'll
assume that the current UPS is one of these).
Since the UPS is fully charged and the power is on, we want to play with the configuration
in /etc/powstatd.conf until STATUS reads OK, and not LOW or FAIL. Provided we are actually
watching the correct serial line, getting STATUS to read OK entails setting initial values
for the output lines DTR and RTS (of course, it makes no sense to try to set initial
values on the input lines). Try adding permutations of init values like:
init dtr 1
init rts 1
until you get the OK status reading.
6. Repeat step 4, but this time pull the plug on the UPS and then reinsert it after a few
seconds. Observe changes in the values for the input lines; it should be easy to determine
what line corresponds to power failure. For example:
CTS DSR DCD RNG DTR RTS STATUS
1 0 1 1 0 1 OK
1 0 1 1 0 1 OK
1 0 1 1 0 1 OK
1 0 1 1 0 1 OK
0 0 1 1 0 1 FAIL <- plug pulled
0 0 1 1 0 1 FAIL
0 0 1 1 0 1 FAIL
0 0 1 1 0 1 FAIL
1 0 1 1 0 1 OK <- plug reinserted
1 0 1 1 0 1 OK
1 0 1 1 0 1 OK
would indicate that CTS going to 0 corresponds to a power failure. If you leave the UPS
unplugged long enough to discharge (this may take quite a while even with a good size
light bulb!), the UPS should signal a battery failure in a similar fashion, e.g.,
CTS DSR DCD RNG DTR RTS STATUS
0 0 0 1 0 1 LOW
0 0 0 1 0 1 LOW
0 0 0 1 0 1 LOW
0 0 0 1 0 1 LOW
7. At this point, you should know the power failure and low battery signals. Now we must
determine the appropriate UPS shutdown signal. Fortunately, for most UPS systems, there
are only 4 possible simple signals. With the UPS on battery power (e.g., unplugged), try
adding each of the following lines into /etc/powstatd.conf in turn:
kill dtr 0
kill dtr 1
kill rts 0
kill rts 1
for each trial, try issuing the command:
% ./powstatd -k
one of the line specifications should cause the desk lamp or radio to turn off; that's the
one you want. Important: be aware that many UPS have a "dead time" after the signal is
sent before the UPS turns itself off; this "dead time" can be as long as 30-45 seconds! So
don't be too impatient here or you won't know which signal is responsible for actually
turning the UPS off.
8. At this point configuration should be complete. For example, for the Cyberpower
Power99 325/385/450/500VA models, a reasonable /etc/powstatd.conf configuration file
reads:
watch ttyS0
fail cts 0
low dcd 0
init rts 1
init dtr 0
kill dtr 1
9. If you have other machines running off the same UPS, include one or more slave entries
specifying their names in the master's configuration file:
slave slave1.domain.edu
slave slave2.domain.edu
The slave machines' configuration files /etc/powstatd.conf should contain a single line
specifying the name of the master machine that is actually monitoring the UPS that also
powers the slave:
watch master.domain.edu
If you intend to run more than 2 slaves off a very large UPS, you will need to adjust the
MAXSLAVES parameter in the source code accordingly and then recompile.
If powstatd is compiled with the appropriate security option enabled, encryption is used
to protect slaves from malicious shutdown messages. An identical password directive should
therefore appear in both master and slave configuration files:
password MyPasswordHere
In addition to encrypting status information, powstatd will encrypt generate and check
timestamps in order to foil replay attacks.
10. Make sure your inittab file contains appropriate lines to invoke powstatd.fail,
powstatd.low, and powstatd.ok:
# UPS signals a power outage.
pf:12345:powerfail:/sbin/powstatd.fail
# UPS signals power restored before the shutdown kicks in.
pr:12345:powerokwait:/sbin/powstatd.ok
# UPS signals low battery power: emergency shutdown.
pn:12345:powerfailnow:/sbin/powstatd.low
11. Edit scripts powstatd.ok, powstatd.fail, and powstatd.low to adjust time parameters,
if desired.
12. "make install", then reboot the machine. If you don't want to reboot, issue instead:
% /etc/rc.d/init.d/powstatd start
% /sbin/init q
How It Works:
powstatd is initiated as a daemon in runlevels 3 and 5.
A UPS can only be in one of three states; OK, FAIL, or LOW. Usually, when the main power
is on, the UPS is operating in the OK state; when power fails, the UPS changes to FAIL
mode, from which it can either recover and return to OK (if the power is restored) or can
move to LOW (if the battery starts running out of juice before the power returns).
powstatd monitors the UPS condition. When the state changes, powstatd writes the new state
of the UPS in /etc/powerstatus and then signals init (the mother of all processes) of the
change in the UPS condition. The init process receives this notice (a SIGPWR interrupt)
and checks /etc/powerstatus to see if it contains "OK", "FAIL" or "LOW".
The contents of /etc/powerstatus tells init (which is configured by the /etc/inittab file)
to run one of three scripts: powstatd.fail, powstatd.ok, or powstatd.low The init process
then removes /etc/powerstatus so as not to be confused on subsequent interrupts.
powstatd.fail
initiates a timed shutdown -h (halt) in background, on the assumption that if power
is restored the shutdown can be cancelled.
powstatd.ok
cancels the running shutdown and notifies all users that power is restored and no
shutdown is imminent.
powstatd.low
cancels the running shutdown and initiates an immediate shutdown -h in foreground;
this means once the UPS tells you the battery is low, you will indeed shutdown
(there is no recovery).
Note that as you halt the machine, the shutdown sequence invokes powstatd one last time,
but this time with the kill flag (-k), forcing the UPS to turn off, but only if the UPS is
indeed in either the FAIL or LOW state (in any case, most supplies will ignore the kill
signal if power is still available). In this fashion, once the power eventually returns
(even after a day or two), the system should automatically restart without intervention.
Troubleshooting:
1. If your machine doesn't seem to notice power status changes even when the UPS daemon
is signalling them, try adjusting the location of the powerstatus file by changing the
value of STATUS in the Makefile and recompiling. Some versions of the init process look in
/var/log/powerstatus rather than the default /etc/powerstatus.
2. If your machine keeps shutting down even when the power is on, you're probably
watching the wrong serial line. To recover, try rebooting in single user mode (issue
"linux 1" at the LILO prompt) and disable powstatd by renaming /etc/powstatd.conf to
something else. Reboot and you should be able to fix the configuration.
3. Some older UPS systems as well as some homebuilt cable connections (see the UPS HowTo)
may require that UPS shutdown signals be sent on the transmission line rather than on one
of the signaling lines. Usually, this implies that a serial break signal (e.g., a long
series of zeros) is required for the UPS to shut down. For these situations, you can use
the special configuration file command
kill break
to obtain the appropriate behavior.
4. If your slave machines keep rejecting seemingly valid status messages from the master
when using encrypted master/slave communication, first make sure they are running the same
version of the software. Otherwise, try changing the definition of "outdated" at compile
time (MAXCLOCKDRIFT) and recompiling. If you are not using NTP or some other mechanism to
ensure that master and slave clocks are reasonably synchronized, you may well be better
off running powstatd compiled without -DSECURE.
5. Some older versions of init are not capable of invoking one of several different
scripts (e.g., powstatd.ok, powstatd.fail, powstatd.low) on receipt of SIGPWR under
different circumstances. Instead, they always invoke the same script, which must then
handle the control logic (i.e., deciding whether to shutdown gracefully, abort a shutdown,
or shutdown immediately) internally (SPARC/Solaris and SGI/Irix apparently fall in this
catagory). If you have such a version of init, look at the sample script powstatd.dumb
included in the distribution for an example of how to go about handling this case.
ACKNOWLEDGEMENTS
I learned a lot from reading the publically-available source code for other UPS monitoring
packages, like genpower, powerd and upsd. I wrote powstatd primarily because the exact
combination of features or configuration options I required were not available with these
other packages.
Peter Galbraith (galbraithp@dfo-mpo.gc.ca), the powstatd Debian package maintainer,
provided numerous suggestions and bug fixes, as did Philippe Troin (phil@fifi.org), who
was the first to suggest using, e.g., MD5-based digital signatures to avoid malicious
shutdowns. Nick Holgate (holgate@debian.org) suggested an extension to powstatd signaling
capabilities in order to support UPS systems that require a break signal for shutdown.
Nicolas Simonds (nic@bridge.com) provided information about changes to the code for both
SPARC/Solaris and SGI/Irix.
TEA, or the Tiny Encription Algorithm, is due to David Wheeler and Roger Needham of the
Cambridge Computer Laboratory. Their implementation, used here, is in the public domain.
Alberto Maria Segre
segre@cs.uiowa.edu
S378 Pappajohn Building
The University of Iowa
Iowa City, IA 52242-1000.