
                         README file for UPSD

                              26 Nov 1996

                               Bob Hauck
                      Wasatch Communications Group
                      http://www.wasatch.com/~bobh


INTRODUCTION

Upsd is a UPS monitor program.  It supports both local monitoring of a
UPS that is directly connected to the computer's serial port and remote
monitoring over a network.  Remote monitoring is done by polling the
master upsd (the one with the direct serial connection to the UPS).
There are a number of options to control the poll interval and the delay
before shutdown.

Upsd can also be run in a "one-shot" mode to detect the UPS status from
a script.  Upsd writes it's log messages using the syslog facility,
which usually puts them into /var/log/messages.

Upsd was developed on a Linux system running the Caldera 1.0 release.


INSTALLATION

Edit the makefile as needed, particularly the installation directories
given near the top.  

Build the program by typing "make" in the source directory.  There
should be no warnings issued.  Then type "make install" as root to
install upsd and the man page.


RUNNING UPSD

The upsd source directory includes two script files.  Upsd.init is a
startup script for Red Hat and Caldera systems and possibly others that
use SysV Init.  Copy upsd.init to /etc/rc.d/init.d.  Edit as needed to
set the UPS monitor device (or host for a slave system).  Then make
symbolic links in the rc3.d and rc5.d directories to automatically start
upsd as part of the boot process.  I use S93ups, like this: 

ln -s ../init.d/upsd.init S93ups

This starts upsd near the end of the boot process, right before rc.local
is executed.  

To modify the upsd.init script for a slave system, change the upsd
startup command line to something like "upsd -c0 -s host", where "host"
is the name or IP address of the master system.

The other script file is upsd.halt.  This one shuts down the UPS if it
is on battery.  I call it from /etc/rc.d/init.d/halt just before the end
of the script, right after the root filesystem is remounted read-only.
The advantage of shutting down the UPS is that all the UPS's the author
is aware of will turn the computer power back on when utility power
returns and the UPS is in a controlled shutdown mode with battery power
still remaining.

You will also need to add power fail and power ok entries to your
existing /etc/inittab, like this:


# When our UPS tells us power has failed, assume we have a few minutes
# of power left.  Schedule a shutdown for 2 minutes from now.
# This does, of course, assume you have upsd installed and your
# UPS connected and working correctly.  
pf::powerfail:/sbin/shutdown -f -h +2 "Power Failure; System Shutting Down"

# If power was restored before the shutdown kicked in, cancel it.
pr:12345:powerokwait:/sbin/shutdown -c "Power Restored; Shutdown Cancelled"


MAKING A CABLE

The master copy of upsd expects to be connected to a UPS via a serial
port.  The control lines on the serial port are used to monitor the
status relays in the UPS.  Upsd does not use the "smart" mode of UPS's
like the APC SmartUPS for two reasons.  First, there are no standards
for the smart mode commands.  And second, the manufacturer of the most
popular models of smart UPS, APC, refuses to release programming
information except under a restrictive NDA that effectively prohibits
releasing source code.

To use the "dumb" mode of your UPS, you must make a cable according to
the following diagram:

    Serial Port                                            UPS

    DCD (8)  <--------------------------+--------------------O
                                        |                     / PWR FAIL
    DSR (6)  <------------+-----XXXXXX--+                    O
                          |                                  +------+
                          |     10K Ohm, 1/4 Watt            O      |
                          |                           LO BAT  \     |
    DTR (20) >------------+-----XXXXXX--+                    O      |
                                        |                    |      |
    CTS (5)  <--------------------------+--------------------+      |
                                                                    |
    GND (7)  <>-----------------------------------------------------+

    RTS (4)  >-----------------------------------------------> SHUTDOWN


The pin numbers shown for the serial port are for a 25-pin male D
connector (wired as DTE).  The corresponding pins for PC's with 9-pin
male D connectors and the pinout for the APC SmartUPS v/s (what I have)
are:

    Signal    25-pin      9-pin       APC SmartUPS v/s
    ==================================================
    DCD         8           1           3 (PWR FAIL)
    DSR         6           6           NC
    DTR         20          4           NC
    CTS         5           8           5 (LO BAT)
    GND         7           5           4 (GND)
    RTS         4           7           1 (RXD or SHUTDOWN)

If you have some other model of UPS, you will need to consult your UPS
manuals for the pin numbers on the UPS end.  Note that this diagram
assumes that the UPS relays CLOSE when the LO BAT or PWR FAIL conditions
become true and are OPEN otherwise.  If your UPS does not support the LO
BAT or SHUTDOWN signals, then you can omit those connections and upsd
will still work (without support those features of course).

The SHUTDOWN signal is expected to be active high.  Upsd will drive RTS
high for at least 5 seconds when a shutdown is requested.  Note that
most UPS's will not honor this if utility power is present.


OBTAINING UPSD

The master ftp site is <ftp://ftp.wasatch.com/pub/users/bobh/Linux>.
Upsd is distributed as a gzipped tar file named "upsd-x.y.tgz", where
x.y is the revision level.


COPYING

Upsd is covered by the GNU General Public License.  See the "COPYING"
file for details.


BUG REPORTS

Please mail any questions or comments to the author, Bob Hauck.  The
email address is:  bobh@wasatch.com.
