* 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/
* Mailing list details: http://lists.exploits.org/

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

==============================================================================
 INSTALLING
==============================================================================

If you are installing these programs for the first time, go read the
INSTALL file to find out how to do that.  This document contains more
information on what all of this stuff does.

==============================================================================
 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, to contact the upsd server running on the
default port 3305 on the local machine, you'd do this:

	/usr/local/ups/bin/upsc localhost

You can compile in a different port number with "configure --with-port".  
That will change the default ports that the programs use.  

To make the client talk to localhost on a specific host (overriding any
compiled-in value), add it after the hostname with a colon, like this:

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

This is handy when you have a mixed environment and some of the systems
are on different ports.  Finally, UPSes have names, and sometimes you have
more than one on a given system.  Here's how you tell them apart.

	/usr/local/ups/bin/upsc bigups@mysystem

	/usr/local/ups/bin/upsc sparky@mysystem

The UPS name goes in front of the @.  If you don't specify a UPS name, it
picks the first one in the configuration files on the server.  The general
form for UPS identifiers is simply:

	[<upsname>@]hostname[:port]

Keep this in mind when viewing the examples below.

==============================================================================
 MANIFEST
==============================================================================

This package is broken down into several categories:

 - drivers - (aka "models") These programs talk directly to your UPS hardware. 

 - server  - upsd serves data from the models (drivers) to the network.

 - clients - They talk to upsd and do things with the status data.

 - cgi-bin - Special class of clients that you can use with your web server.

==============================================================================
 DRIVERS
==============================================================================

These programs provide support for specific UPS models.

You can run them directly, and the basic form of that looks like this:

	/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

You should only use this form when testing or debugging the drivers, as
it's messy and there are better ways to start them.  For many of the
drivers, you can now configure them by using the ups.conf file.  Let's
define an example UPS that we'll call "sparky".  It uses the apcsmart
driver, and is connected to /dev/ttyS1 - the second serial port.  The
configuration in ups.conf then looks like this:

	[sparky]
		driver = apcsmart
		port = /dev/ttyS1

Easy.  Now you can start the driver and just tell it to look in the
"sparky" section of the ups.conf to find its parameters:

	/usr/local/ups/bin/apcsmart -a sparky

-a means "autoconfigure", and the argument tells it which section to use.

 AUTOCONFIGURE COMPATIBILITY
 ---------------------------

This only works on drivers that have been upgraded to support ups.conf.
Check the table below to see if a driver has been converted as of the
time of this writing.

Also, you can find out if a driver has been converted by calling it with
-h to display the built-in help.  If the help mentions "-a <id>" to
autoconfigure itself, then it will work.  

If your driver doesn't support -a, you can still use ups.conf to configure
it for upsd, but you will have to start the driver the old way where you
supply all the parameters on the command line.

 EXTRA ARGUMENTS
 ---------------

Some drivers require additional arguments to properly communicate with
your hardware.  If it doesn't detect your UPS with no extra arguments,
then check the driver's help (-h) to see what options are available.
Newer drivers that support -a (see above) may also support additional
configuration options via -x.

For example, the apcsmart driver allows setting "cable" to "940-0095B".
To do this on the command line, it would look like this:

	/usr/local/ups/bin/apcsmart -x cable=940-0095B /dev/ttyS1

Remember that ups.conf is the right way to handle driver configuration,
so you should store that value in there instead and use -a.  Here's how
you put that cable definition in ups.conf:

	[sparky]
		driver = apcsmart
		port = /dev/ttyS1
		cable = 940-0095B

After that, every time you start apcsmart with "-a sparky", it will
know to use that cable setting.

If your driver is old and does not support -a yet, it will also not
support the -x / ups.conf technique.  Check the driver's help (-h)
and/or man page for a list of which flags and values may be set (if
any).

 DRIVER CONVERSION
 -----------------

You may have gathered by this point that having the drivers all support
the common -a and -x interfaces would be much easier for everyone.  If
your favorite driver does not support this code, consider converting it
and contribute a patch back to the project.

*** After 0.45.5, all old-style drivers will be REMOVED from the tree.
***
*** This means you will lose support for your hardware unless the
*** driver is converted to the new structure.
***
*** See the FAQ for more information.

 HARDWARE SUPPORT TABLE
 ----------------------

Check this table to see which driver or drivers support your hardware.
Drivers that have been upgraded to support ups.conf and the -a/-x
options are noted in the table.


        aeg              - AEG Protect S. xxx models

	apcsmart         - APC Smart-UPS, Back-UPS Pro, Matrix-UPS models
			   * supports ups.conf

        belkin           - Belkin Regulator Pro
			   * supports ups.conf

	bestferrups801-807

			 - Best FerrUPS 8.01-8.07 models
			   * supports ups.conf

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

	bestuferrups     - Best Power Micro-Ferrups models

	bestups          - Best Power models: (newer, usually beige)
			   * supports ups.conf

                           - Fortress (FOR)
                           - Fortress Telecom (FTC)
                           - Patriot Pro (PRO)
			   - Patriot Pro II (PR2)
                         
                           The SOLA 520 and 620 are also recognized.

			   This driver will probably also work with other
			   PhoenixTec protocol hardware.

	cyberpower       - Cyber Power Systems units (experimental)
			   * supports ups.conf

			   This one is still in the very early stages.
			   It will probably only give useful numbers on
			   the AVR700.

	engetron         - Engetron Jr units

	everups          - EVER Sp. z o.o models
			   * supports ups.conf

                           - NET *-DPC
                           - AP *-PRO 

	fentonups        - Fenton Technologies models:
			   * supports ups.conf

	                   - PowerPal
	                   - PowerOn
	                   - PowerPure

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

                         - PowerGuard PG-600

			 - PowerCom SMK-800A

			 This driver implements the Megatec protocol, so
			 other Megatec hardware will probably work with it.

	genericups       - Many contact closure models -
                           see "Generic UPS driver" below 
			   * supports ups.conf

        hidups           - Experimental driver for USB HID UPSes on Linux
                           * supports ups.conf

                           Some units that have been used with this driver:

                           - APC Back-UPS Pro 350 USB
                           - APC Back-UPS 500 USB
                           - MGE Ellipse USB

                           NOTE: not built by default.  Read the FAQ
                           to find out how to build/install/use this one.

	hp		 - HP Powertrust models
			   * supports ups.conf

	ipt-anzen	 - IPT Anzen models (experimental driver)

	masterguard	 - Masterguard UPS hardware
                           * supports ups.conf

	mge-ellipse	 - MGE Pulsar units
                           * supports ups.conf

	mgeups		 - MGE Pulsar/Comet/Galaxy units

	multilink	 - Liebert units (via MultiLink cable)

	mustekups	 - Mustek Electronics units
                           - also some Belkin Regulator Pro Net models

	newapc           - APC smart protocol units
                           * supports ups.conf

			   - Back-UPS Pro
			   - Smart-UPS
			   - Matrix-UPS

			   Note: older Matrix-UPS units may have better
			   results with apcsmart instead

	newpowercom	 - Trust 425/625
			 - Powercom units
			 - Advice Partner/King PR750
			   * supports ups.conf

			   This replaces the powercom and ups-trust425+625
			   drivers.

	newvictron	 - IMV/Victron hardware
			   * supports ups.conf

			   This driver replaces the older victronups driver
			   below.

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

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

	sec		 - SEC protocol units (various sources)
                           * supports ups.conf

        sms              - SMS Ltda (Brazilian) units
                           - Manager III 1300
                           - Manager III 650

	toshiba1500      - Toshiba 1500 series units

	tripplite	 - Tripp-Lite SmartUPS units
			   * supports ups.conf

	ups-trust425+625 - *Unsupported driver* - try newpowercom first.
			 - Trust (KingPro) 425/625
                         - Belkin Regulator Pro also reportedly works

	upseyeux	 - Microdowell BBox models

	victronups	 - IMV/Victron models
                           - Match Lite
                           - NetPro

For another take on this list, try the web page: 

	http://www.exploits.org/nut/library/compat.html

 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.

This type of UPS tends to be cheaper, and only provides the very simplest
data about power and battery status.  Advanced features like battery
charge readings and such require a "smart" UPS and a driver which
supports it.

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

 DRIVER CONTROL
 --------------

UPS drivers can now be controlled with upsdrvctl.  It uses the ups.conf
to start and stop the programs that support the UPS hardware.  This only
works on the new drivers that support ups.conf, so check the table
above to be sure.

To start all UPS drivers in the ups.conf, just use "start":

	/usr/local/ups/bin/upsdrvctl start

To stop all drivers, use "stop":

	/usr/local/ups/bin/upsdrvctl stop

To start or stop just one, list the UPS name after the command:

	/usr/local/ups/bin/upsdrvctl start sparky
	/usr/local/ups/bin/upsdrvctl stop sparky

With upsdrvctl, you can install a bunch of different UPSes on different
machines and just put "upsdrvctl start" in their startup scripts.  It
will figure out the right drivers from the ups.conf on each system.

In the old days, you had to change the startup scripts to reflect the
configuration of each system, and it made a mess for those of us with
several systems that would otherwise have identical startup files.

You can also use upsdrvctl to shut down all of your UPS hardware
with the shutdown command.  Use this command with caution!

	/usr/local/ups/bin/upsdrvctl shutdown
	/usr/local/ups/bin/upsdrvctl shutdown sparky

You should read the shutdown.txt file in the docs subdirectory to
learn more about when to use this feature.  If called at the wrong time,
you may cause data loss by turning off a system with a filesystem
mounted read-write.

==============================================================================
 NETWORK SERVER
==============================================================================

upsd is responsible for passing data from the model modules to the client
programs via the network.  You should start it after whatever driver is
appropriate for the UPS you have.  Continuing with the example where
the package was installed in /usr/local/ups, the startup line would
look like this:

	/usr/local/ups/sbin/upsd

 ARGUMENTS
 ---------

upsd supports several arguments to change its default behavior.  Start it
with -h to see more information on what they are.

 MULTIPLE UPS MONITORING
 -----------------------

There is no hard limit to the number of local UPSes that upsd can monitor
aside from your system's resources.  Simply define a section for each UPS,
start the appropriate driver, and upsd will serve data for it.  Once this
is done, you can use programs like upsc to read the status.

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 ups.conf:

	upsc upsname@localhost

"upsname" corresponds to the name of the section in the ups.conf.  To
configure a UPS called "zoidberg", it would look something like this:

	[zoidberg]
		driver = futureups
		port = /dev/lobster

Multiple local UPS monitoring works best on systems with many serial
ports.


==============================================================================
 UPSMON
==============================================================================

upsmon is a very important daemon that provides the basic functionality
you expect from UPS monitoring software - system shutdowns when the power
fails.  Technically, it is a "client", but it has its own section in
the documentation because it is so important.

You configure it by telling it about UPSes that you want to monitor in
upsmon.conf.  Each UPS can be defined as one of three possible types:

 - Master - This UPS supplies power to the system running upsmon, and
   this system is also responsible for shutting it down when the battery
   is depleted.  This occurs after any slave systems have disconnected
   safely.

   If your UPS is plugged directly into a system's serial port, the
   upsmon on that system should define that UPS as a Master.

 - Slave - This UPS supplies power to the system running upsmon, but 
   this system can't shut it down directly.  This system will shut down
   the operating system before the master turns off the power.

   Use this mode when you run multiple computers on the same UPS.
   Obviously, only one can be connected to the serial port on the UPS,
   and that system is the master.  Everything else is a slave.
   
 - Monitor-only.  This UPS will still generate notifications about
   status changes (on battery, on line, etc.) but no shutdowns of the
   local system result from critical situations on that UPS.

For a typical home user, there's one computer connected to one UPS.
That means you run a model driver, upsd, and upsmon in master mode.

Here's how you configure upsmon to suit your environment.

 MASTER MODE
 -----------

In this mode, upsmon keeps the system running until all slaves disconnect
safely.  This allows them extra time to bring down the operating
system.  The master system then runs its own shutdown sequence, which
usually includes a call to the model driver to kill the power after the
filesystems have been remounted read-only.

	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.

 MONITOR-ONLY 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.

 SHUTDOWN CONFIGURATION
 ----------------------

The stock command to shut down the system is "/sbin/shutdown -h +0".
That works in most places.  If your system needs to do something else
when it's time for upsmon to shut it down, edit the upsmon.conf and 
change SHUTDOWNCMD to that new value.

 PRIVILEGES
 ----------

upsmon must start as root on most systems as it needs to exec a shutdown 
command.  As of version 0.45.1, the default mode for upsmon makes
it split into a privileged/unprivileged process pair shortly after
entering the background.  The unprivileged process does most of the
heavy lifting - contacting upsd, keeping track of UPS status data, and
so on.  The root process just waits for the shutdown signal.  When
that arrives, it will write out the power down flag and call your 
SHUTDOWNCMD.

If you need to run upsmon in the old style where the whole thing always
runs as root, call it with the -p flag.  To change the user that the
unprivileged process becomes, specify it with -u.

If your system has capabilities and fine grained permissions, then full
root access is not necessary.  That style of configuration is beyond the
scope of this document.

 ADDITIONAL INFORMATION
 ----------------------

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

 - The man page - upsmon(8)

 - big-servers.txt in the docs subdirectory

 - shutdown.txt in the docs subdirectory

 - The stock upsmon.conf that comes with the package

==============================================================================
 CLIENTS
==============================================================================

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 once looked like this:

	rkpent:~$ upsc localhost
	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 this list has
grown quite large as more features have been added to the software.  You
can use upsc along with other Unix tools like cut, grep, sed, and awk to
monitor UPS equipment easily in shell scripts.

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 lightweight 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 [<log format>]

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.

 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 user name and password.  You'll need
to use a valid combination as defined in your upsd.users file.  Once 
that's entered correctly, the UPS should perform a front panel test
(fptest), assuming it's capable of such a task.

This will only work if the user/password combo are valid and if that user
has been granted permission to actually do whatever command you specify.
See the example upsd.users file for more information on this.

==============================================================================
 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, go get it and install it before continuing.

You can get the source here:

	 http://www.boutell.com/gd/

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

Given recent versions of Apache, you will probably have to use 
"Options FollowSymLinks" to make that work.  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.

 HOSTS.CONF
 ==========

The CGI programs use this configuration file to limit the hosts that
they may speak to.  If you tell one of them to talk to a host that isn't
exactly matched by an entry in this file, they will refuse.  This keeps
random people from using your web server's programs to open connections
to other hosts.

So, if your CGI programs say "Access to that host is not authorized",
check the hosts.conf first.

 MULTIMON
 ========

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.

You can add "&refresh=nn" to your multimon.cgi URL if you want it to
instruct your web browser to reload the page every nn seconds.

 UPSSTATS
 ========

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 IMG SRCs a few images that draw bars showing current
values.  They are drawn by upsimage, which is the next section:

 UPSIMAGE
 ========

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

upsset provides several useful administration functions through a web
interface.  You can use upsset to kick off instant commands on your UPS
hardware like running a battery test.  You can also use it to change
variables in your UPS that accept user-specified values.

Essentially, upsset provides the functions of upsct2 and upscmd, but
with a happy pointy-clicky interface.

upsset will not run until you convince it that you have secured your
system.  You *must* secure your CGI path so that random interlopers
can't run this program remotely.  See the upsset.conf file.  Once you
have secured the directory, you can enable this program in that
configuration file.  It is not active by default.

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

The main URL:

	http://www.exploits.org/nut/

There is also a mailing list for general queries and discussion about
this software.  It typically moves around 50-100 messages per month at
the time of this writing.  To join, send "subscribe ups" to  
majordomo@lists.exploits.org.  

If you just want to receive an automatic message when a new version
(release or testing) is posted, subscribe to upsdevannounce instead.  That
list is moderated, and will only be used for these notifications.

Finally, there are developer lists called upsdev and hidups.  upsdev is
for any development, and hidups is just for that one driver.  These are
not install help lists, and any such mails probably will be ignored.

The submission address is just the list name @ lists.exploits.org.

The mailing lists are archived on the web:

	http://lists.exploits.org/

Try running some searches against the archives.  Many times, problems have
already been answered by someone else.

There is more documentation in the docs/ directory within the source 
tree.  Be sure to read through the files in there (especially the
FAQ) before mailing the list for help.  Many times the questions have
already been answered in the files which are right in front of you.

==============================================================================
 MAKING YOUR OWN CLIENTS (UPSFETCH)
==============================================================================

The upsfetch.o library can be linked into other programs to let them grab
data from a UPS running this software.  The clients upsc and upsct are
provided as lightweight examples of how to retrieve data using those
functions.  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
==============================================================================

Here's how the version numbering has been proceeding:

 - Everything is called 0.x since planned features are lacking.  Once
   the package includes all of the items marked for 1.0, then it will
   become 1.0.

 - The middle number is currently incremented with each new project.
   For example, the 0.44.x releases focused on upsmon.  Before that,
   0.43.x introduced instant commands and clients to use them.

   This middle-number scheme is not expected to continue after 1.0.

 - "-pre" versions are developmental snapshots of the tree.  They are
   potentially broken as code is reworked between releases.  Typically
   the last -pre version will be nearly identical to the release that
   follows, except for any bug fixes and documentation updates.

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

Additional documentation can be found in the docs subdirectory.  Of
particular interest to those looking to create a new driver are 
model-arguments.txt and new-modules.txt.  Also see skel.c and the
existing new-style drivers that use main.c to see how it's done.

Information on the architecture and how it all fits together is in the
design.txt file.  In short, there's a lot more documentation out there.

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

Invensys Energy Systems provided the SOLA/Best "Phoenixtec" protocol
document currently residing at the following URL:

	http://www.exploits.org/nut/library/protocols/sola.html

PowerKinetics technical support provided documentation on their MiniCOL
protocol, which is archived in the NUT protocol library online:

	http://www.exploits.org/nut/library/protocols/minicol/

Cyber Power Systems contributed a 700AVR model for testing and driver
development.

MGE UPS Systems provided a Pulsar Ellipse premium 500 for development
and expansion of the new hidups driver, along with extensive information
on their implementation of the HID power class and other documents.
That documentation is online at this URL:

	http://www.exploits.org/nut/library/protocols/mge/

All donated equipment can usually be seen on the big multimon page:

	http://www.exploits.org/cgi-bin/ups/multimon.cgi