  Monitoring an APC Smart-UPS[TM] with smupsd
  David E. Myers <dem@skyline.rtp.nc.us>
  Version 0.9, August 18, 1997

  This is the documentation for smupsd, a daemon which monitors an APC
  Smart-UPS[TM] under Red Hat[TM] Linux.
  ______________________________________________________________________

  Table of Contents:

  1.      Overview

  2.      Synopsis

  3.      Dependencies

  4.      Installation

  5.      Operation
  ______________________________________________________________________

  1.  Overview

  smupsd monitors an APC <http://www.apcc.com> Smart-UPS[TM] under Red
  Hat[TM] Linux <http://www.redhat.com>.  Should power fail, smupsd will
  power down the system and the UPS in an orderly fashion.

  smupsd has the following features:

  o  Shuts down the system and the UPS based on either remaining UPS
     battery charge or elapsed time since power failure.

  o  UPS parameters can be monitored live from any host with the
     graphical monitor program upsmon, written in Java[TM].

  o  UPS parameters can be logged to a file for analysis and reporting.

  o  When additional systems share the same UPS, instances of smupsd
     running on these systems can read UPS parameters from the one
     running on the system serially connected to the UPS (master/slave).

  o  Network access from remote hosts can be controlled via the
     /etc/hosts.allow file.

  2.  Synopsis

  smupsd [-d] [-p] [-h] [-s] [-t threshold] [-m minutes] [-l logfile]
  [-i log interval] <device or host>

     -d Debug mode; don't shut down the system.

     -p Don't power down the UPS after shutting down the system.

     -h Monitor a remote host instead of a tty device.

     -s Secure mode; only accept network requests from hosts specified
        numerically in /etc/hosts.allow.  Note that upsmon communicates
        with smupsd over the network.
     -t <threshold>
        Battery level shutdown threshold (default: 40%).  If set to 0,
        don't shut down based on battery level.

     -m <minutes>
        Shut down after a power failure has lasted this many minutes,
        regardless of battery level threshold.

     -l <logfile>
        Log UPS parameters to this file.  (default: /var/log/smupsd,
        specified in the provided startup file).  Under Red Hat Linux,
        the log will be rolled once a week.

     -i <log interval>
        Log file write interval in seconds (default: 600).

  3.  Dependencies

  smupsd is Copyright (c) 1996, 1997 David E. Myers.  It is freely
  redistributable under the terms of the GNU General Public License.
  See the file COPYING for details.  The included runtime libraries for
  the Bongo GUI builder are Copyright (c) 1996, 1997 Marimba, Inc.
  <http://www.marimba.com>.

  This is a pre-release version of smupsd, but it's getting pretty close
  to the feature set I intend to have in version 1.0.  In its current
  form, smupsd reliably shuts down your Linux system when the battery
  level of your Smart-UPS reaches a certain level (default 40%,
  changeable with the -t option), or a specified time in minutes has
  elapsed (settable with the -m flag), whichever occurs first.  Slave
  versions of smupsd running on separate machines on the same Smart-UPS
  can be notified of power failures by a master version running on the
  machine cabled to the UPS.

  In addition, the upsmon graphical tool can be used to monitor selected
  UPS parameters live from any host.  To run this tool you must have
  Java[TM] 1.0.2 on your PATH.

  smupsd communicates with a Smart-UPS using information obtained from
  the reverse engineering efforts of Pavel Korensky and Kevin D.
  Smolkowski.  APC has been no help in determining the ``proper'' way to
  communicate with a Smart-UPS.  Additional features were contributed by
  Marc Merlin, <marcsoft@magic.metawire.com>

  Network access control is based on version 7.5 of the TCP/IP daemon
  wrapper package by Wietse Venema <wietse@wzv.win.tue.nl>.

  smupsd requires a release 2.X Linux kernel and the updated version of
  init that goes with it.  These are both standard with Red Hat Linux
  4.0 and later, and are optional with Red Hat Linux 3.0.3.

  As of version 0.6, smupsd requires the RPM package linuxthreads-0.5-1
  or later (included with Red Hat Linux 4.1 and 4.2, and available from
  ftp.redhat.com for earlier versions).  This is because smupsd now uses
  kernel threads to reliably monitor your UPS while simultaneously
  responding to network requests for UPS parameters.

  Note that power level monitoring is not available with the Smart-UPS
  v/s.  When monitoring a v/s, smupsd will schedule a system shutdown as
  soon as it recognizes a power failure unless you use the -m option to
  specify a time period and use the -t option to specify a threshold of
  0.

  4.  Installation

  To install smupsd, install the RPM with rpm or glint.

  NOTE: If upgrading smupsd, you should shut down the currently running
  version first.

  Connect your Smart-UPS to your system with the APC Smart Signalling
  Cable included with the APC PowerChute product.

  Create a symbolic link from the serial device (to which the Smart-UPS
  is attached) to /dev/ups, e.g.,

  ln -s /dev/cua0 /dev/ups

  Alternately, edit /etc/rc.d/init.d/smupsd.init and change the device
  name passed in on the command line.

  Start the daemon as root either by rebooting, or manually:

  /etc/rc.d/init.d/smupsd.init start

  Watch for log messages in /var/log/messages.  When the daemon starts,
  you should see something like the following:

  Nov 14 10:27:09 devil smupsd: Monitoring UPS on /dev/ups
  Nov 14 10:27:09 devil smupsd: Listening for messages on port 4321
  Nov 14 10:27:09 devil smupsd: Logging to file /var/log/smupsd
  Nov 14 10:27:09 devil smupsd: UPS battery charge level is 100%

  If you don't quite trust this daemon, you can run it in debug mode by
  passing it the -d flag on the command line.  In debug mode, smupsd
  will monitor the Smart-UPS, but will not actually shut your system
  down or power down the Smart-UPS.  To pass smupsd the -d flag, edit
  the smupsd.init file as mentioned above.

  Alternately, you might wish to start smupsd with the -p flag, which
  inhibits smupsd from commanding the Smart-UPS to power down after your
  Linux system has shut down.  This can be useful if you are powering
  multiple systems from a single Smart-UPS, but you only want one of the
  systems commanding the UPS to power down.

  Note that with current versions of kernel 2.0.X and LinuxThreads, the
  daemon process will show up multiple times in the process table
  because the kernel currently assigns different process IDs to each
  thread.  This looks funny, but is harmless.

  If you have additional Linux systems running on the same Smart-UPS,
  you can still use smupsd to shut them down.  You pass the name of the
  host which is physically connected to the Smart-UPS to the smupsd
  running on a slave machine wtih the -h flag.

  The upsmon graphical tool can be used to monitor selected UPS
  parameters live from any host by starting it with the name of the host
  to which the Smart-UPS is attached as the only command line argument.
  If no argument is specified, upsmon monitors localhost.

  By default, smupsd will accept network requests from upsmon or another
  smupsd that originate from any host.  Depending on your network
  configuration, this could present a security problem.  When smupsd is
  started with the -s option, it obeys the parameters in the network
  access configuration files /etc/hosts.allow and /etc/hosts.deny as
  described in the the hosts_access(5) man page.  Note that only numeric
  host addresses are currently supported.

  For example, to restrict the use of the upsmon program from any host
  but the one on which smupsd is running (i.e., localhost), pass the -s
  flag to smupsd in the smupd.init file and add the following to
  /etc/hosts.allow:

  smupsd: 127.0.0.1

  When logging to a file, smupsd only logs numeric information separated
  by white space to make it easier to produce reports from the logs.
  For example, one might import a log file directly into a spreadsheet
  program and graph UPS battery temperature over the course of a week.
  The data written to the log file is, in order:

  1. Date of last UPS sample (localized format).

  2. Time of last UPS sample (localized format).

  3. Battery charge (percent).

  4. Output load (percent).

  5. Input line voltage.

  6. Minimum input line voltage.

  7. Maximum input line voltage.

  8. Output voltage.

  9. Output frequency (Hz).

  10.
     Battery voltage.

  11.
     Battery temperature (C).

  The log file will look something like this:

  08/18/97 14:55:00 100 29 122.2 118.9 122.8 122.2 60.00 27.6 31.9
  08/18/97 15:05:10 100 29 122.8 118.3 122.8 122.8 60.00 27.6 31.9
  08/18/97 15:15:09 100 29 120.9 119.6 122.8 122.8 60.00 27.6 31.9
  08/18/97 15:25:11 100 29 121.5 120.2 123.5 121.5 60.00 27.6 31.9

  5.  Operation

  smupsd works as follows:

  The Smart-UPS is polled for its current status every 10 seconds.

  The battery charge level is logged 1) at startup; 2) whenever it
  reaches 100%; and 3) whenever it changes by 10% or more from the last
  value logged.

  When the Smart-UPS switches to battery power, it must remain on
  battery for 30 seconds for smupsd to declare a power failure.  This is
  so transient switches to battery (such as power flickers and self-
  tests) are ignored.

  When smupsd determines that the power has failed, it logs the fact and
  continues to monitor the battery power level at 10 second intervals.

  If at any time during a power failure the power returns, smupds will
  again wait for 30 seconds of samples which indicate that the Smart-UPS
  is no longer on battery power before logging the restoration of power.

  While the UPS is on battery, if the battery power level drops below a
  set threshold (default: 40%) or the number of minutes specified with
  the -m flag have elapsed (default: no limit), smupsd notifies the init
  process of the loss of power.

  With the default /etc/inittab provided with Red Hat Linux this will
  cause a system shutdown to be scheduled for 2 minutes from now.  All
  users on the system will be notified of the impending shutdown.

  If power returns, smupsd will notify init, which will cancel the
  shutdown, if it hasn't already started.

  After 2 minutes, the system will begin an orderly shutdown.  One of
  the last processes terminated will be smupsd itself.  When smupsd
  receives a SIGTERM after requesting a system shutdown, it will
  instruct the Smart-UPS to power down after a predefined delay (by
  default 20 seconds) (unless smupsd was started with the -p flag).

  Therefore, shortly after system shutdown is complete, the Smart-UPS
  will power off.  It should come back on again after the power is
  restored.  Whether or not your system comes back on at this point is
  system-dependent.

