
                         INSTALL file for UPSD

                      26 Nov 1996, Bob Hauck
                      Wasatch Communications Group
                      http://www.wasatch.com/~bobh

                      9 June, 2000, Michael Robinton
                      BizSystems, Michael@bzs.org

                      3 Nov, 1999, Russell Magee
                      Mount Royal College, rmagee@mtroyal.ab.ca

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 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 can also be run in "wait" mode from a script with the filesystem 
dismounted to facilitate power recovery in situations where the UPS
can not be turned off, the host is a "slave" or the file system(s) are
software raid and must be dismounted to prevent damage.

Upsd was developed on a Linux system running the Caldera 1.0 release.
It has been tested on a variety of systems running kernels up to 2.4.


INSTALLATION

Edit the makefile as needed, particularly the installation directories
given near the top. Uncomment the SOCKS5 equate if you wish to have
support for socks servers. I've tested it for sock5, it should work for
socks4 but has not been tested.

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 four script files.  

SCRIPT: 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.

SCRIPT: upsd.halt  

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.

SCRIPT: rc.upsd

can be used to init, wait for power recovery, and shutdown the UPS
with a minimum of command line arguments. It was developed for use on a
Slackware system and may be used on other systems if the appropriate links
and entries are made in the rc.d/init.d directory tree. All the parameters
used by upsd are entered at the top of the rc.upsd script file.
rc.upsd contains self documenting help. Type ./rc.upsd -h for further
information and read man 8 upsd. 'rc.upsd' has settable parameters.

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.  

for Caldera

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"

for Slackware

# When power fails, shutdown (kill the ups - reboot on recovery).
pf::powerfail:/sbin/shutdown -f -r +5 "THE POWER IS FAILING"

# You only need this entry for hosts actually connected to a UPS and
# that use "enhanced " mode. Do not use this or "enhanced" mode for 
# slaves unless they share the UPS with their master host.
# If the ups battery gets low, go down in a hurry, reboot on recovery
pn::powerfailnow:/sbin/shutdown -f -r +1 "THE POWER IS FAILING NOW"

# If power is back before shutdown, cancel the running shutdown.
pg:12345:powerokwait:/sbin/shutdown -c "THE POWER IS BACK"

# If power comes back in single user mode, return to multi user mode.
ps:1:powerokwait:/sbin/init 3

NOTE: that shutdown is specified with -reboot.

Copy rc.upsd to /etc/rc.d
Also add the following script lines to rc.S, rc.K, rc.6:

  rc.S		as the last entry

  # invoke upsd to monitor ups
    if [ -x /etc/rc.d/rc.upsd ]; then
      . /etc/rc.d/rc.upsd
    fi

  ---------------------------------------------------------

  rc.K		as the last entry

  # invoke upsd to monitor ups
    if [ -x /etc/rc.d/rc.upsd ]; then
      . /etc/rc.d/rc.upsd -recall	# recall previous ups status
    fi
#NOTE THE -r OPTIONS
  ---------------------------------------------------------

  rc.0/rc.6		before the "# Now halt or reboot"
			line as the next to last entry.

  # check for powerfail recovery or shutdown
  if [ -x /etc/rc.d/rc.upsd ]; then
    /etc/rc.d/rc.upsd -wait -recall
  fi
#NOTE THE -r -w OPTIONS
  -----^ insert before existing end code ^------
  # Now halt or reboot.
  echo "$message"
  [ ! -f /etc/fastboot ] && echo "On the next boot fsck will be FORCED."
  $command -f

  ---------------------------------------------------------

SCRIPT: upsdummy

is a upsd control utility for use with upsd operating in 'Dummy' mode.
As a master, the script simply provides a simulated UPS status to
the daemon which in turn serves it to network clients. All other 
upsd operations are inhibited. As a slave, the upsd daemon operates 
normally in every respect except that the status information is
provided by upsdummy rather then the actual UPS or slave network
connection. 'upsdummy' has settable parameters.

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, a simple cable can be made according
to the following diagram:

   DB9 SER DB25                                       UPS

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


The diode in the RTS line protects the led in the UPS from excessive 
backward voltage. The diode is a standard 1 watt power rectifier type 
of diode. The cable will work without the  diode, however, it is 
present in many UPS manufacturer's cables.


Some UPS's (like Tripp Lite) separate the GND and SHUTDOWN return lines in
which case your cable should either tie those lines together or 
be made according to this diagram (preferred).

   DB9 SER DB25                                       UPS

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

   (7) RTS (4)  >------------>|-----------------------+---->|-+~
                   1N4001, 1N4740 or equiv        SHUTDOWN    |
                                                              x
                                                              x
                                                              x
                                                              |
   (5) GND (7)  >---------------------------------------------+


The pinouts for the APC SmartUPS v/s and the Tripp Lite LAN 2.1 series
are shown below in the table below.

   Signal   9-pin   25-pin     APC SmartUPS v/s   Trip Lite (Lan 2.1)
   ======================================================================
   DCD        1        8        3 (PWR FAIL)            5 (PWR FAIL)
   DSR        6        6        NC			NC
   DTR        4       20        NC                      NC
   CTS        8        5        5 (LOW BAT)             2 (LOW BAT)
   TD         3        2        NC                      1 (COMMON PF, LB)
   RTS        7        4        1 (RXD or SHUTDOWN)     2 (SHUTDOWN POS)
   GND        5        7        4 (GND)                 4 (GND -SHUTDOWN)
 
Belkin ReSource F5C520c UPS
===========================

This UPS comes with what looks like a standard DB-9 M-F serial cable but
it is wired differently. There appear to be no internal resistors (the
UPS may have an internal circuit with the pullup resistors for the status
lines). The pinout appears to be as follows:

    DB-9 (PC side, female)               DB-9 (UPS side, male)
    ----------------------               ---------------------
    Pin                                  Pin     Meaning
    ---                                  ---     ------
    1   (DCD) <--------------------------- 1     LOW BATTERY
    3   (Tx)  ---------------------------> 5     ?? (PC's Tx tied to GND?)
    4   (DTR) ---------------------------> 4     UPS Shutoff (when on battery)
    7   (RTS) ---------------------------> 7     Power to UPS status lines
    8   (CTS) <--------------------------- 8     ACFAIL

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 of 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:  hauck@codem.com. Upgrade to 2.x by Michael Robinton,
michael@bizsystems.com.
