* Network UPS Tools Documentation
*
* Russell Kroll <rkroll@exploits.org> and others, see CREDITS file.
*
* Released under the GNU GPL - see COPYING for details.
*
* Program support page: http://www.exploits.org/nut/

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
======

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

	/installpath/bin/model /dev/port

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

	/usr/local/ups/bin/apcsmart /dev/ttyS1

The genericups driver requires an additional flag since it is actually
many little drivers rolled into one.  You must specify -t <num> to 
pick which set of values is right for your hardware.

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

	apcsmart         - APC Smart-UPS, Back-UPS Pro, Matrix-UPS models

        belkin           - Belkin Regulator Pro

	bestfort	 - Best Power models: (older, usually black)
			   - Fortress

	bestuferrups     - Best Power Micro-Ferrups models

	bestups          - Best Power models: (newer, usually beige)
                           - Fortress
                           - Fortress Telecom
                           - Patriot Pro
                         
                           The SOLA 520 is also recognized.

	engetron         - Engetron Jr units

	fentonups        - Fenton Technologies models:
	                   - PowerPal
	                   - PowerOn
	                   - PowerPure

                         - Effekta MI/MT/MH models (2502 cable)

                         - PowerGuard PG-600

	genericups       - see "Generic UPS driver" below 

	ipt-anzen	 - IPT Anzen models (experimental driver)

	mustekups	 - Mustek Electronics units

	newapc           - APC smart protocol units (experimental driver)

	optiups          - Opti-UPS models: (experimental driver)
                           - PowerES
                           - PowerPS (untested)
                           - PowerVS (untested)

	powercom         - Advice Partner/King units
                         - PowerCom models (replaces ups-trust425+625, above)

	toshiba1500      - Toshiba 1500 series units

	ups-trust425+625 - Trust (KingPro) 425/625
                         - Belkin Regulator Pro also reportedly works

	victronups	 - IMV/Victron models
                           - Match Lite
                           - NetPro

 
Generic UPS driver
==================

The "genericups" driver will support many models that use the same basic
principle to communicate with the computer.  This is known as "contact
closure", and basically involves raising or lowering signals to indicate
power status.  

See generic-ups.txt in the docs subdirectory for more information,
including a list of supported equipment.

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.  Continuing with the example where
the binaries have been installed in /usr/local/ups/bin, the startup line 
would look like this:

	/usr/local/bin/upsd

Extras
------

	* Change UDP listening port

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

	/usr/local/bin/upsd -u 1234

	* Change both (UDP and TCP) listening ports

	As above, but this sets both ports to the same value.

	/usr/local/bin/upsd -p 1234

	* Change TCP port to one value and UDP port to another value

	/usr/local/bin/upsd -p 1234 -u 5678

	Order matters here.  If you do -u first, the -p will override it.

        * Bind to a specific interface

        -i <IP> will let you find to the interface numbered <IP>.

	* Multiple UPS monitoring

	upsd can also monitor multiple local UPSes.  Just add additional
	"UPS" lines to the upsd.conf.  There is no hard limit other than
	the memory available in your system.  Once that is done, you can
	use programs like upsc to read the status back from them.

	To check the first/only UPS on your system:

		upsc localhost

	To check another UPS on your system, assuming you have more
	than one in the upsd.conf:

		upsc upsname@localhost

	... where "upsname" is the same name you gave it in the upsd.conf.

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

CLIENTS
=======

Current clients: upsc upsct upslog upsmon multimon.cgi upsstats.cgi
                 upsimage.cgi upsct2 upsset.cgi upscmd

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
STATUS: OL
UTILITY: 113.7
BATTPCT: 100.0
ACFREQ: 60.00
LOADPCT: 023.9
UPSTEMP: 038.2
UPSIDENT: RKPENT
LOWXFER: 103
HIGHXFER: 132
WAKEDELAY: 060
LINESENS: H
AMBTEMP: 27.68
CONTACTS: F0
AMBHUMID: 041.6

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.

The meaning of these values is documented.  See protocol.txt in the
docs subdirectory for more information.

upsc is also a good place to start if you're interested in writing your
own client to talk to upsd.  The source is relatively simple, and it's
easy to start fetching variables with this code base.

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 are 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/ups/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.

upslog can also use a customized log format, given as any and all parameters
after the first three required ones.  A summary of these parameters is given
when upslog is run with insufficient arguments.  Escape sequences in the
format string are substrings that are bounded with '%'.

%%            will insert a single %

%TIME format% will insert the current time.  The format is a variation on
              the format used by strftime(3).  The foratting escape used here
              are the same as for strftime, except that @ is used instead of
              % to avoid ugly parsing code.  So, to insert the current hour
              in 24 hour format you would use %TIME @H%.  Multiple escapes
              can of course be given (e.g. %TIME @H@M@S%).

%HOST%        will insert the hostname of the machine that upslog is running
              on (as given by gethostname(3)).

%UPSHOST%     will insert the host of the ups you are monitoring (the first
              commandline argument

%PID%         will insert the pid of upslog

%ETIME%       will insert the number of seconds since January 1 1970 0000Z
              aka Epoch Time, hence ETIME.

%VAR varname% will insert a variable retrieved from the ups.  Use upsc or
              upsct to get a list of these variables.

Note that the space after TIME and VAR can be any character.  Logical
choices are space, _, or -.  So %VAR_upstemp% is the same as %VAR upstemp%.

If you want to test out your format string, you can use - as the log file
and upslog will run in the foreground, logging to stdout.

upsmon
======

upsmon is a very important daemon that provides the basic functionality
you expect from UPS monitoring software - system shutdowns when the power
fails.  It can monitor a given UPS in one of 3 ways:

1. Monitor-only - you get notifications about changes in status
   (on battery, on line, etc.) but nothing else happens as a result.

2. Master - as above, but this UPS supplies power to this system and
   this system is responsible for shutting it down when the battery
   has been depleted.

3. Slave - similar to master, only the UPS is not actually attached to
   this box, so this system must shut down immediately before the master
   powers down the UPS.

upsmon can monitor multiple UPSes simultaneously in a mixture of these
3 modes since 0.44.0.  It can also handle computers with multiple 
power supplies and multiple UPSes to match.

More explanations follow, so if that didn't make sense, read on...

Monitor mode
------------

You can configure a UPS strictly for monitoring by declaring the number
of power supplies serviced by it to be 0.  You do that with a config
entry like this:

MONITOR someupsname@somehost 0 nopass slave

The password and "slave" don't actually do anything here, but are included
to keep the number of fields constant.

Master mode
-----------

In this mode, upsmon takes on the responsibility of sending the powerdown
command to the UPS when the situation requires it.  This is usually due to
a UPS draining a battery while the AC power is out.  Configure it with
a line like this:

MONITOR someups@somehost 1 mypassword master

Note that the password must match the corresponding ACCESS line in the
upsd.conf.  This example assumes that "someups@somehost" runs just 1
of this system's power supplies.  If you have more than one power supply,
be sure to set this appropriately.

Note that upsmon will shut down *all* UPSes that are listed as "master"
in the config file when the situation gets bad enough to warrant a 
shutdown.  

Example:

 - You have two power supplies.  Each one has its own UPS.
 - This particular computer needs both power supplies to keep running.
 - Someone trips over the cord to one of the UPSes.

Eventually, that UPS will drain and reach a critical state.  upsmon will
notice this situation and command a shutdown for *both* UPSes since it
is master for both of them.  Any slaves attached to these units will
see the "forced shutdown" flag and shut themselves down too, so they
will be OK.

Slave mode
----------

This mode is configured much like master mode, except for the last keyword.

MONITOR someups@somehost 1 mypassword slave

If upsmon is running in slave mode for a given UPS, it will run the
local shutdown command immediately when a UPS goes critical.  This can
happen one of two ways:

 - The UPS reaches a low battery state while running on battery power.
 - The UPS has the "forced shutdown" flag set by a master upsmon process.

The idea is to shut down quickly and safely before the master upsmon 
comes along and turns the power off.

Configuration
-------------

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.

Permissions
-----------

upsmon must run as root on most systems as it needs to exec a shutdown 
command.  If your system has capabilities and fine grained permissions, 
then full root access is not necessary.

Additional information
----------------------

More information on configuring upsmon can be found in these places:

 - big-servers.txt in the docs subdirectory
 - shutdown.txt in the docs subdirectory
 - The stock upsmon.conf in the conf subdirectory

upsct2
======

This program is similar to upsc and upsct, but it displays the possible
values for variables that can be changed.

upscmd
======

Some models support "instant commands".  upscmd provides an interface to
access those commands that may be supported in your hardware.  To see
what's available, use the -l command:

	/usr/local/ups/bin/upscmd -l <ups>

Continuing with the localhost example, that's:

	/usr/local/ups/bin/upscmd -l localhost

You should get a list of a few interesting things on most models.  To
actually invoke one of them, specify the ups and command to run:

	/usr/local/ups/bin/upscmd localhost fptest

At this point, upscmd will ask for a password.  This should be whatever's
in your upsd.conf in the ACCESS lines for the system that you're on.  Once
that's entered correctly, the UPS should perform a front panel test
(fptest), assuming it's capable of such a task.

Note - this functionality requires MANAGER access, so make sure that your
upsd.conf grants the right access levels to the right hosts.

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.

What happens next depends on your compiler's configuration.  If the 
install target for gd puts everything in a sane place, your compiler and
linker should pick it all up and be happy with it.  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.

upsset.cgi
==========

This program allows you to set variables like upsct2, but it's done 
through a web interface.  There is also a separate screen for issuing
instant commands ala upscmd.  You must create user and system accounts 
in upsset.passwd before this will do anything useful

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.

Also, there is more documentation in the docs/ directory within the source
tree.  Be sure to check there (especially the FAQ) before mailing the list.
Many times the questions have already been answered in the files right
in front of you.

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.

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.

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

Additional documentation can be found in the docs subdirectory.

ACKNOWLEDGEMENTS / CONTRIBUTIONS
================================

Fenton Technologies contributed a PowerPal 660 to the project.  Their open 
stance and quick responses to technical inquiries are appreciated for 
making the development of the fentonups driver possible.

Bo Kersey of VirCIO (http://www.vircio.com) provided a Best Power 
Fortress 750 to facilitate the bestups driver.  

These models can usually be seen on the big multimon page:
http://www.exploits.org/cgi-bin/ups/multimon.cgi
