* Smart UPS Tools Documentation
*
* Russell Kroll <rkroll@exploits.org>
*
* Released under the GNU GPL - see COPYING for details.
*
* Program support page: http://www.exploits.org/~rkroll/smartupstools/

DESCRIPTION
===========

This is a developing project to monitor a large assortment of UPS hardware.
Many models have ports on the back to allow other devices to check on
their status.  If it gives basic information about the power and battery
status, it can probably be supported without too much difficulty.  More
advanced features on the higher end models are also supported to allow
tracking of values over time such as temperature and voltage.

Network communications are used so that multiple systems can monitor a
single physical UPS and shut down together if necessary without any
special "sharing hardware" on the UPS itself.

NETWORK INFORMATION
===================

These programs are designed to share information over the network.  In
the examples below, "localhost" is used as the hostname.  This can also be
an IP address, fully qualified domain name, and so on.  You can also
specify a port number as part of the hostname in case your upsd process
runs on another port.

In the case of the program upsc:

	/usr/local/ups/bin/upsc localhost

... contacts localhost on port 3305 which is the default.  If you changed
the port number with ./configure --with-udpport, it uses whatever you put
there.

	/usr/local/ups/bin/upsc localhost:1234

... contacts localhost on port 1234.  This is handy when you have a mixed
environment and some of the systems are on different ports.

Keep this in mind when viewing the examples below.

PROGRAMS INCLUDED
=================

Here are some short descriptions of the programs that are included in
this package.

MODELS
======

Current models: smartups backups backupspro ups-trust425+625

These programs provide support for specific UPS models.  The general
model for running them is:

	/installpath/bin/model /dev/port

So, to run the smartups driver on port ttyS1 given an install path of
/usr/local/ups, you'd do:

	/usr/local/ups/bin/smartups /dev/ttyS1

Model information
=================

	smartups         - APC Smart-UPS models (also Matrix-UPS)
	backupspro       - APC Back-UPS Pro models
	backups          - APC Back-UPS models
	ups-trust425+625 - Trust (KingPro) 425/625

SERVER
======

upsd is responsible for passing data from the model modules to the client
programs via the network.  You should start it after whatever module is
appropriate for the UPS you have.  upsd needs to know where to find the
data that your model-supporting module is collecting.  So, start it like
this:

	/installpath/bin/upsd /statepath/module-port

Continuing with the above example of a Smart-UPS on ttyS1 and a state path
of /var/state/ups, the startup line would look like this:

	/usr/local/bin/upsd /var/state/ups/smartups-ttyS1

Note that the "/dev/" has been stripped off for sanity's sake.

Starting with 0.41.0, you can add "UPS" lines to the upsd.conf file and
run upsd without any arguments.  Specifying state filenames on the command
line is now depreciated behavior and will probably be removed in a future
version.

UPSes specified on the command line are added *in addition to* the ones
from the config file.  So, don't list them twice or you'll just waste
memory and clock cycles.

Extras
------

	* Change listening port

	upsd can listen on a port other than the one set at ./configure 
	time.  To enable this mode, use the -p switch like so:

	/usr/local/bin/upsd -p 1234 /var/state/ups/smartups-ttyS1

	* Multiple UPS monitoring

	upsd can also monitor multiple local UPSes as of 0.40.3.  Just add
	the state filenames to the command line.  There is no hard limit
	other than the memory available in your system.

	To monitor a UPS other than the primary (first one listed), change
	the hostname slightly.

	Instead of doing "upsc localhost", you'd do "upsc ups-1@localhost"
	or "upsc ups-2@localhost".  Remember that this counts from 0, so
	"upsc ups-0@localhost" will get always you the primary UPS.  If
	you don't specify which ups name to contact, you will get the
	primary UPS by default.

	This is probably only useful on systems with many serial ports.

	For meaningful UPS names, use the "UPS" lines in the config file
	instead.  The command line method forces names like ups-0 and ups-1.

CLIENTS
=======

Current clients: upsc upslog upsmon upsstats.cgi upsimage.cgi

Clients talk to upsd over the network and do useful things with the data
that's being collected.  Some of them are designed for basic command line
usage while a special subset can be run as CGI programs from within your
web server.

upsc
====

upsc provides a quick way to test the functionality of your setup.  To
run it, just do "upsc localhost" and see what comes back.  The results
vary greatly based on the system and the hardware being monitored.  A
typical run on the example configuration looks like this:

host: localhost
MFR: APC
MODEL: SMART-UPS 700
SERIAL: WS9643050926
UTILITY: 119.6
BATTPCT: 100.0
STATUS: OL
UPSTEMP: 041.4
ACFREQ: 60.00
LOADPCT: 024.9
LOWXFER: 103
HIGHXFER: 132

Every value known to upsd about your ups is returned, so the list may get
quite large as more features are added.  This output can also be parsed
with tools like "cut" for quick hacks in shell scripts and the like.

More information about what the values returned can be found in the docs
subdirectory.

upsct
=====

Like upsc, but this version uses TCP connections to get things done.  This
will probably perform a lot better over links where UDP packets get
corrupted by noisy links or dropped by firewalls.

upslog
======

upslog is a daemon that will periodically ask a upsd for information on
the ups being monitored and then log it to a file.  This data can then be
parsed by other programs to create interesting looking graphs, reports, or
similar.  You call it like this:

	/installpath/bin/upslog hostname /log/file interval

So, to log values from localhost into a file called /tmp/ups at 30 second
intervals with the previously established example paths, use the
following...

	/usr/local/bin/upslog localhost /tmp/ups 30

Due to service delays, the time will drift slightly as the program runs.
It will run a poll, write the data, then sleep for the interval.  Since
the act of fetching and logging the data takes time, things will slowly
advance.  As an exaggerated example, one poll may be at 12:00:00, then
12:00:31, 12:01:02, and so on.

Users requiring tighter timing are encouraged to examine the upsfetch
part of this documentation for information on creating custom clients.

upsmon
======

upsmon is a very important daemon that provides the basic functionality
you expect from UPS monitoring software - system shutdowns when the power
fails.  

** Note: until further improvements are added, the UPS will not be 
   commanded off after a shutdown occurs. 

Running upsmon is simple.  The format is:

	/installdir/bin/upsmon host

So, to monitor the UPS on the example setup, run this (as root)...

	/usr/local/bin/upsmon localhost

Being root is important here since upsmon has to be able to fire up the
system shutdown process.  Since mere users shouldn't be able to do this,
root access is required.  

Since distributions and operating systems vary widely, you should find out
what the appropriate shutdown command is and edit the upsmon.conf file to
reflect this.  The stock value provided may not function on other systems.

CGI Programs
============

These are a special subset of the clients that provide UPS information
through a web interface.  This requires a web server with a sane CGI
implementation.  Apache is the most common server for this sort of thing
but others should be able to cope too.

These programs are not installed or compiled by default.  To compile them,
do "make cgi".  To install, "make install-cgi".  If you receive errors
about "gd" during configure, get it from http://www.boutell.com/gd/ and
compile it on your system.

*** gd note, 13 July 1999

Note: it looks like Boutell has gotten out of the gd business entirely.
So, if you like a good thing, come get a version from my web site before
the Unisys landsharks start giving me grief just for storing it.

http://www.exploits.org/~rkroll/smartupstools/gd/

I recommend using version 1.3.

***

What happens next depends on your compiler's configuration.  I put libgd.a
in /usr/local/lib and all of the *.h files from the gd distribution in
/usr/local/include.  This keeps egcs happy, so everything compiles.
If those directories are not searched on your system, consider changing
things so that they are *or* install gd somewhere else.

Once the CGI programs are installed, it's now a matter of making your web
server find them.  I usually point a symlink from my cgi-bin directory to
/usr/local/ups/cgi-bin and enable symlinks for that part of the tree.
Apache seems to like this just fine.  

Assuming a fairly stock configuration of both Apache and these programs,
setting this symlink should be sufficient.

	cd /usr/local/apache/cgi-bin ; ln -s /usr/local/ups/cgi-bin ups

Don't forget "AllowSymLinks" in the case of Apache.  If this is an
unacceptable parameter on your system for security reasons or otherwise,
point the link the other way and force the programs to install directly
under the cgi-bin directory.  They don't care where they are as long as
the config files are readable.

multimon.cgi
============

This program lets you watch many different systems from one web page.
It also provides links to other pages with more information on each.
It figures out which systems to monitor by reading the hosts.conf file.
Be sure to set this up with each system that you'd like to monitor.

This is probably the best one to bookmark if multiple systems are
routinely monitored in your configuration.

upsstats.cgi
============

upsstats provides a page that attempts to look like Powerchute with the
help of upsimage.  It shows some basic information about the system being
monitored and then sources a few images that draw bars showing current
values.

upsimage.cgi
============

This is usually called by upsstats via IMG SRC tags to draw either the
utility voltage, battery charge percent, or load percent.  It may be
useful to call from other pages, but usually isn't.

SUPPORT / HELP / ETC.
=====================

Besides the program support page, there is also a mailing list that is
used to put out occasional release announcements and answer questions.  At
the time of this writing, it is extremely low volume.  To join, send
"subscribe ups" to majordomo@lists.exploits.org.  The submission address
is just ups@lists.exploits.org.

UPSFETCH / MAKING YOUR OWN CLIENTS
==================================

The upsfetch.o library can be linked into other programs to let them grab
data from a UPS running this software.  For an example of how this is
done, inspect the upsc source code.  Other programs may need this library
for linking.  In this case, do "make install-misc" and it will put that
and the header file in a directory called misc under your install path.

NAMING ISSUES
=============

"Smart UPS Tools" doesn't really describe things very well now that other
APC models are supported in addition to units from completely different
manufacturers.  Send suggestions to the mailing list - maybe a good
one will come along and this will all be renamed.

VERSION NUMBERING
=================

The versions are supposed to work like this...

Everything is currently 0.x since planned features are lacking.  Once
all of them are coded and stable, it will become 1.0.

"-pre" versions are potentially broken, but are used to make sure things
work after making major changes.

UPGRADING FROM 0.34
===================

If you previously ran 0.34 or earlier, things will seem a lot different.
This is because all of the server code has been rewritten to accomodate
the new architecture that accepts multiple models and vendors.  The
network code was also redone to fix a number of bogus byte alignment and
ordering problems that my previous protocol had.

If there are features or other things that seem to be missing from
previous version, bring them to my attention in case I've overlooked
something.

HACKING / DEVELOPMENT INFO
==========================

Additional documentation can be found in the docs subdirectory.
