Installation Instructions for UPSMON
------------------------------------

   UPSMON version 2.1.3

   Aug 15, 1998
   New Corridor Information Services
   upsmon@newcorridor.com
   ftp://newcorridor.com/pub/upsmon/upsmon-2.1.3.tar.gz


------------------------------------------------------------------
1. Unpack the distribution files
 
   gunzip upsmon-2.1.3.tar.gz
   tar -xvf upsmon-2.1.3.tar


------------------------------------------------------------------
2. Compile step.

   This software is targeted to run on BSDI systems, although it 
   should compile and run on most versions of UNIX without too
   much additional effort.

   There are two makefiles included with the distribution.
   
   makefile.gnu  - if you run GNU make on your system
   makefile.bsdi - if you run the BSDI default make

   The GNU makefile is the default and the distribution comes
   with makefile.gnu already copied to Makefile.  If you want
   to setup makefile.bsdi as the default, simply copy
   makefile.bsdi to Makefile.  Or you can use the -f command
   line switch to specify a either makefile.gnu or
   makefile.bsdi when you run make.

   To compile ...

      make

      or

      make -f makefile.bsdi

   If you complete the compile without any errors you should
   have two binaries:

      upsmond  - upsmon daemon
      upsstat  - upsmon status reporting utility


   If you want to remove all object files and binaries before
   rebuilding ...
   
      make clean

   
------------------------------------------------------------------
3. Install binaries.

   When you finish the compile step, move the upsmond and upsstat
   binaries to the directory location of your choice such as:

      /usr/local/bin
      
   Because you may have a series of command line switches to set
   when you load the upsmond daemon (as outlined below in step 4),
   you may want to use the shell scripts provided to simplify
   starting and stopping the monitor.  These shell scripts
   included in the distribution can also go in /usr/local/bin.  If
   you change path locations or command line options, you will
   need to fixup the shell scripts accordingly.  Be sure to read
   through step 4 carefully to understand how to use the command
   line switches.

   start-upsmon   (start upsmond with appropriate command line options)

   stop-upsmon    (stop upsmond)

   The start-upsmon shell script assumes that the upsmond binary
   is located in /usr/local/bin and launches with the standard
   defaults:

        serial port:  /dev/tty00
       local socket:  /tmp/upsmond.sock
           PID file:  /var/run/upsmond.pid
           log file:  /var/log/daemon.log
     temp directory:  /tmp
     retry interval:  5  (5 minutes)
 
                   
   You will also want to install an entry in your /etc/rc.local
   startup script (BSDI) to launch the upsmond daemon when your
   system re-starts.

     In /etc/rc.local ...

     # Put additional local daemons here...

     echo -n " upsmond"; /usr/local/bin/start-upsmon
  
     Be sure to read step 4 carefully to determine how to use the
     command line switches.


------------------------------------------------------------------
4. Command line switches - configuration.

   UPSMON configuration is handled using command line options.
   The available options are:

   -h : display the usage help

   -i : PID file name

        This is the name of the PID (process id) file that is 
        updated by the upsmond daemon after it loads.  This file
        is used to easily determine the PID of the running daemon
        when sending signals such as terminate (using kill).
        The standard convention on BSDI systems is to keep these
        PID files in /var/run.  The default PID file name is:

        /var/run/upsmond.pid

        If you want to change this default PID file name, you can
        override it with the -i switch.

        ex.
 
        upsmond -i /var/run/ups.pid


   -l : syslog facility

        upsmond uses the system logger (syslog) to direct log
        messages to the console and the log files.  The log
        facility setting determines to which log file upsmond
        will send messages.  The default log file that upsmond
        will use is daemon.log.  This means that with the
        default log facility setting "UPSMON messages" will be
        mixed in with all other messages in daemon.log.

        If you want to setup a dedicated or specific log file to
        hold only "UPSMON messages, you would use this setting
        to override the default log facility with one of the
        LOG_LOCALn facility settings.  If you choose to use a
        LOG_LOCALn facility setting, you will also need to add
        the appropriate entry in your /etc/syslog.conf config
        file.  UPSMON supports the following log facility
        settings.

        LOG_DAEMON    ... daemon.log (default)
        LOG_LOCAL0    ... user defined 0
        LOG_LOCAL1    ... user defined 1
        LOG_LOCAL2    ... user defined 2
        LOG_LOCAL3    ... user defined 3
        LOG_LOCAL4    ... user defined 4
        LOG_LOCAL5    ... user defined 5
        LOG_LOCAL6    ... user defined 6
        LOG_LOCAL7    ... user defined 7

        ex.        

        upsmond -l LOG_LOCAL1  (set syslog facility to LOG_LOCAL1)
  
        If you want to use a user defined log file (recommended
        preference), you will also need to put the appropriate
        entry in /etc/syslog.conf.

        For example:

        To setup a dedicated log file called upsmon.log in the
        /var/log directory, choose a user defined log facility.
        In this example we use LOG_LOCAL1.  In /etc/syslog.conf,
        place the following comment and log file assignment.

        # upsmond - UPS monitor log
        local1.*                          /var/log/upsmon.log

        
        If this is the first time you are setting up this log file
        you will need to create the file on the file system before
        re-inititializing syslogd to see the new log file (syslogd
        will not automatically create new log files).  To create
        the new log file, use touch.

        touch /var/log/upsmon.log
        
        Then you will need to re-initialize syslogd to pick up the
        new configuration.  Send a hangup signal to the running
        syslog daemon to reset.

        kill -1 `cat /var/run/syslog.pid`

        
        Now when you load and run upsmond with the syslog facility
        set to LOG_LOCAL1, all upsmond log messages will be
        directed to your new log file /var/log/upsmon.log.

       
        upsmond -l LOG_LOCAL1  (set syslog facility to LOG_LOCAL1)


   -p : serial port name

        This is the RS-232 serial port that you connect your
        APC SmartUPS to.  On BSDI systems, the default port name
        for the first RS-232 port is /dev/tty00.  This is the
        default so if you attach your SmartUPS to this port
        you don't need to supply this parameter - just use
        the default.  If you are attempting to run this on
        something other than BSDI, you will need to supply the
        proper device name of the serial port on your system.

        ex.

        upsmond -p /dev/tty00  (use serial port #1 - default)

        upsmond -p /dev/tty01  (use serial port #2)


   -r : retry limit

        This is the interval in minutes that the power must remain
        down after a power failure before the upsmond daemon will
        inititiate the system shutdown sequence.  The default is 5
        minutes.  Here's how the retry interval works.  If the
        power fails, upsmond enters a timing state and begins
        timing how long the power stays down.  If the power
        remains down for the full interval as specified in the
        'retry limit' setting, then upsmond will intitiate a
        shutdown sequence which will shutdown the system and put
        the SmartUPS into sleep mode.

        If the power comes back up at anytime during the retry
        interval, the upsmond daemon resets the counters and
        starts from the top.  This means that if the power comes
        back up during the retry interval and then drops again,
        the timing starts over again for the full retry limit.
        If you want to change the default 5 minute retry limit,
        you can override it with the -r switch.

        ex.
 
        upsmond -r 8    (set retry limit to 8 minutes)
        


   -s : socket name
        
        This is the name of the UNIX domain socket (local IPC)
        used to provide IPC communication to the upsmond daemon.
        The upsstat status utility uses this socket interface to
        request status information from the upsmond daemon.  The
        default socket name and location is:

        /tmp/upsmond.sock

        If you want to change this default socket name, you can
        override it with the -s switch.

        ex.
 
        upsmond -s /var/run/ups.sock

        Remember, if you change the name or location of the
        local socket, you will need to pass the same socket
        name to the upsstat utility when you run it as well:

        upsstat -s /var/run/ups.sock



   -t : temp directory
        
        The upsmond daemon uses a temporary directory.  The
        default temp directory is /tmp .

        If you want to change the default temp directory,
        you can override it with the -t switch.

        ex.
 
        upsmond -t /var/tmp


------------------------------------------------------------------
5. A note about the serial cable

   In order for the SmartUPS devices to function correctly
   it's important that you use the proper cable supplied
   by APC that ships with the unit.  To my knowledge, there
   are two cable models supplied by APC that are designed to
   work with the SmartUPS devices:

     #990-0024B  - serial cable
     #990-0024C  - serial cable
   
   We have only tested with the 990-0024C cable so we can't
   vouch for the 990-0024B cable.  Be sure to use the correct
   cabel - if you attempt to use a standard RS-232 cable or
   some other mis-configured cable, you can actually cause damage
   to the UARTs on the SmartUPS device or your PC system.

   I have some documentation that illustrates how to configure
   a cable that will work with the SmartUPS devices, however
   we have not verified that these specifications are correct
   and don't care to publish information that we have not
   tested.  If you would like a copy of these cable specifications
   send us an email at upsmon@newcorridor.com and we would
   be glad to provide the information to you.



------------------------------------------------------------------
6. Using upsmond and upsstat
   
   If you have everything setup properly, you should be able
   to start upsmond.  If you are using the start-upsmon
   script, run that.  Otherwise, launch directly from the
   command line using the appropriate command line switches
   (see step 4 above).

   Any errors encountered during load time and initialization
   will be reported directly to the console.  Most of these
   errors, if encountered, will be configuration errors such
   as invalid serial device names, invalid file names or path
   locations for the local socket, PID file, etc.  If you
   encounter errors, check your configuration.  It may be that
   the defaults that are taken by UPSMON are not suitable on your
   system, in which case, you will need to over-ride the 
   appropriate command line setting to correct the
   problem.

   If no errors are encountered, then the upsmond daemon should
   be loaded and should have successfully established
   communication with the UPS device.  

   You can verify that the daemon is talking to the UPS device
   by running the upsstat utility.  The upsstat utility will
   communicate with the running upsmond daemon through the local
   UNIX socket and ask the upsmond monitor to query the UPS device
   for a series of status values.  (The upsstat utility does not
   communicate directly with the UPS device, but rather goes
   through the upsmond daemon which handles all the handshaking
   with the UPS device).  The upsmond daemon will return the set
   of status values to the upsstat utility which will then be
   displayed on the console.  The status display will tell you a
   series of useful information including serial number, line
   voltages, battery voltages, last battery replace date, load
   level, etc.  The display should be self-explanatory.

   Check the log file (either the default daemon.log or the
   user-defined log file if you set one up) to be sure that
   the upsmond daemon is properly sending messages through the
   system logger.  All log file entries will have the following
   format and will contain the "UPS:" tag so it is easy to grep
   for UPS log entries (if you need to pull entries out of
   daemon.log).

   "Aug 5 14:23:49 puma UPS: upsmond daemon started - version 2.1.3"
                        ^^^

   The upsmond daemon will log start, stop, battery low, power
   failure, power resume, and system shutdown messages to the
   logfile.

   Finally, you should test the ability of the upsmond daemon
   to gracefully shutdown your system in the event of a power
   failure.  The easiest way to do this is to simply unplug
   your APC SmartUPS device from the AC power.  It should continue
   to provide battery backup power to your system.  You should
   notice almost immediately a "power failure" message posted
   to the console.  As the "retry interval" (default is 5 minutes)
   continues to countdown, upsmond will display the time left
   to shutdown (reported in seconds) on the console about once
   every minute.  Finally, when the "retry interval" expires,
   upsmond will initiate a shutdown sequence, put the APC
   SmartUPS in sleep mode, and the system should shutdown
   gracefully.  

   After the system shuts down and the SmartUPS device is
   sitting in sleep mode, plug the UPS back in.  This should
   result in the system performing a normal cold boot.

   Once back in, check the log file.  You should see a series
   of "power fail" messages and the final shutdown message
   recounting the sequence of events.

   If power is restored before the full "retry interval" expires,
   upsmond will display a "power back" resume message on the
   console and the upsmond monitor will simply reset waiting for
   the next power failure event.  You can test this as well by
   unplugging the UPS from the AC power and plugging it back in
   before the "retry interval" expires.


------------------------------------------------------------------
7. Technical support

   UPSMON should be straightforward to use.  While we have had the
   monitor up and running for close to a year now, we have it
   installed on only one server, a BSDI 3.0 system.  As of this
   date, August 1998, this is the first attempt to put the
   software into any kind of distribution, so undoubtedly, some
   issues may arrise.

   Also bare in mind that, while we have attempted to build the
   software to run on a general UNIX platform, it has only been
   tested on a BSDI system.  While it should be straightforward to
   bring the software up on other UNIX systems, especially the
   Berkeley variations, we have not, as of yet, put in any effort
   outside of BSDI.  Some aspects, like the use of Berkeley style
   UNIX domain sockets (for local IPC) may not necessarily port
   as easily to AT&T style systems.

   Please send any feedback, questions, suggestions, and problem
   reports to:

     upsmon@newcorridor.com

   Drop us an email if you would like to be included on a mailing
   list to receive notices about new releases, enhancements, etc.
   We will setup an automated email list if the interest is there,
   but for now, we expect the number of users to be small and will
   manage the list by hand.

   We would also like to hear from you if you are successful using
   UPSMON on system's other than BSDI.
   
   If you find the software useful, we would appreciate a small
   donation of $25 to help us offset our support costs.  Please
   send payment in the form of a check to:

      New Corridor Information Services
      1464 Madera Rd. Unit N, #182
      Simi Valley,  CA  93065

      make check payable to: NCIS
   
   Please understand, as a freely distributed software product, it
   is difficult for us to allocate time and resources to provide
   support.  The $25 donations will enable us to provide better
   support and improve the product with enhancements.



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


   Thanks for using UPSMON.

                                 Bob Pill
                                 New Corridor Information Services
                                 bobp@newcorridor.com

