* smartupstools documentation - Russell Kroll <rkroll@exploits.org>
*
* Released under the GNU GPL - see COPYING for details.
* 
* Version 0.30 - big changes behind us, more additions ahead

Program support page: http://www.exploits.org/~rkroll/smartupstools/

How to use the programs, short version

First, a short description of what these binaries do..

 - upsd: daemon.  Talks to the ups via your serial line and answers udp
   queries from clients that arrive via the network.

 - upsmon: daemon.  Talks to upsd and shuts the machine down when the
   battery is low and the line power is gone.  Walls a lot to tell users
   what's going on.

 - upsstats.cgi: user program.  Generates the HTML for the main status page.

 - upsimage.cgi: user program.  Called by IMG SRC tags in status pages.

 - multimon.cgi: user program.  Monitors multiple upsds on one page.
 
 - upsc: example program.  Shows how to use fetch in your own programs.

 - upslog: daemon.  Logs values from a UPS at a specified interval.

OK, assuming you have configured and installed the program already, here
is how you actually use it to keep an eye on things.

A note about the networking capabilities
========================================

Since all the communications between upsd and the clients is UDP based,
they need not live on the same computer.  This design lets you run upsd
on the computer with the serial connection to your UPS, and then run
upsmon on all of the other computers that actually draw power from that UPS.

For example, I have 3 BSD/OS machines at the office that draw power from
one Smart UPS 2200.  One of them has a serial cable going to the UPS, and
runs upsd.  All three run upsmon, and thus monitor the UPS even though they
aren't directly connected.

These networking abilities also let you run the CGI-based stats programs
on a machine that may have nothing to do with your UPS at all, but happens
to be your web server.   The CGI programs are optional and in fact aren't
installed with a normal "make install".  Use "make install-cgi" to put
them in the default location under the main install path.

All this happens over UDP port 3301.  This was pulled out of the air one day.
If you want to use some other port, edit the protocol.h and change the
#define UDPPORT line, then recompile the programs.

Using upsd
==========

upsd needs to run as much as possible.  For this reason, you should start it
from your system startup scripts.  On Slackware systems, this is as simple
as dumping "/usr/local/ups/upsd" in /etc/rc.d/rc.local.  Similar techniques
apply to other Linux distributions and other operating systems as well.

upsd will use the syslog to tell you when it has started successfully.

There are two command line options to upsd:

 -s - choose another serial port.  Use this to override the one in the 
      configuration file.

 -p - choose another UDP (network) port.  This overrides the UDPPORT
      setting in netprotocol.h.  This is good for running multiple upsds
      on the same host, since they can't all use the same port.

Generic note about host names
=============================

If you move your upsd to another network port with -p, you need to tell
the various client programs to look for it on that new port.  This works
much like a port in a URL.  Just add ":portnum" to the host.

So, instead of doing "upsmon myhost", do "upsmon myhost:3350" if your
upsd is now running on port 3350.  This also applies to entries in hosts.conf
and any URLs you may create to go directly to the CGI programs.

Using upsmon
============

upsmon, like upsd, should also run whenever possible.  On a machine that
is to monitor a ups, add a line to your startup scripts to start upsmon.
Such a line might look like "/usr/local/ups/upsmon 1.2.3.4", with your
machine's IP address in place of the 1.2.3.4, obviously.

CGI program note
================
Previously, the programs installed themselves into a directory under
your web server's document root, similar to "/www/cgi-bin" by default.
As a sanity preservation technique, I now have them install to a cgi-bin
directory under the main installation path.  

One way to set this up easily is to set a symlink in your web server's
cgi-bin directory to the UPS cgi-bin directory.  On a stock Apache 1.3
install, cd into /usr/local/apache/share/cgi-bin and do 
"ln -s /usr/local/ups/cgi-bin ups" assuming you installed this software 
in /usr/local/ups.  

One catch if you are running Apache - be sure FollowSymLinks is enabled
for your cgi-bin directory.  Otherwise, it will refuse to chase that
link into the real directory, leaving you with a nice error for every hit.
Check your config files (usually access.conf) to see what the current
settings are.

Using upsstats
==============

upsstats is a CGI program, and as such, you must invoke it through your
web server with a browser.  Assuming you have it installed into your
/cgi-bin directory, accessing the following URL will allow you to see
what's going on in your UPS..

http://your.machine.dom/cgi-bin/upsstats.cgi

Making a bookmark to this script or linking to it from another page is an 
easy way to return to it in the future.

Using upsimage
==============

upsimage is also a CGI program like upsstats, but it is intended to be
called by IMG SRC requests inside the page that upsstats generates.
You can source the images from it directly if you like, but they may
look rather odd outside the table scheme of the normal upsstats page.
Most users will probably never need to touch upsimage directly.

Using multimon
==============

multimon is invoked just like upsstats.  Either link to it from a page or
feed the URL to your favorite browser manually.  It will attempt to display
information about every system listed in your hosts.conf.  Systems that are
unavailable or have values out of normal ranges will have yellow and red
used to indicate a possible problem.

The page created also contains links to upsstats.cgi so you can see the
powerchute lookalike page corresponding to the UPS you just clicked on.

Using upsc
==========

upsc, while intended as a small demonstration program of the upsfetch
library, can also be used to verify operation of the UPS where no
web browser is available or desired.  It takes just one parameter -
the host you wish to query.  To request the information of a machine 
called "elvis", you'd do...

$ upsc elvis

The responses you get depends on what's out there.  What you see is a
dump of the entire information struct that gets passed from the server
to the client.  Various bits of this struct are used in the other programs
(upsstats, upsimage) to generate those interesting looking web pages.

Using upslog
============

upslog is intended to be used in conjunction with some other utility that
will read the data logged and make interesting graphs or similar.  It takes
three parameters - ups host, log file, and logging interval.

To log values from our "elvis" host into /tmp/ups every 30 seconds, use
the following...

$ upslog elvis /tmp/ups 30

The interval is currently implemented with a simple sleep().  Due to the
time required to service the polls and write to the file, this means it
will drift along slightly as time goes by.  The first poll might be at
12:00:00, then another at 12:00:31, then 12:01:02, and so forth.  

- The format of the data logged is as follows:

<date> <time> <battcap> <utility> <upsload> <status> <upstemp> <outputfreq>

- The format of the fields works out like this..

date: YYYYMMDD - sorts nicely and doesn't have any Y2K implications.
                 call me in 9999 and I'll add a digit for Y10K compliance.

time: HHMMSS - time as you'd expect it.

battcap: UPS battery capacity (percentage) - 0.0 to 100.0

upsload: UPS load (percentage) - 0.0 to more than 100.0 when overloaded

status: Bitmapped status field, value is in hex.

upstemp: UPS internal temperature.  Note - value is degrees C.

outputfreq: Frequency of power being passed (Hz) - should always be 60.00 here.

- The log file is flushed after every write, so tail -f should work nicely.

Other issues
============

upsimage uses the gd library from http://www.boutell.com/ for quick 
generation of GIF images.  If you have something that needs speedy 
graphical representations of data that's being written in C, you should 
check it out.

