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

Network UPS Tools is a collection of programs which provide a common
interface for monitoring and administering UPS hardware.  It uses a
layered approach to connect all of the parts.

Drivers are provided for a wide assortment of equipment.  They
understand the specific language of each UPS and map it back to a
compatibility layer.  This means both an expensive "smart" protocol UPS
and a simple "power strip" model can be handled transparently.

This information is cached by the network server upsd, which then
answers queries from the clients.  upsd contains a number of access
control features to limit the abilities of the clients.  Only authorized
hosts may monitor or control your UPS hardware if you wish.  Since the
notion of monitoring over the network is built into the software, you
can hang many systems off one large UPS and they will all shut down
together.

Clients such as upsmon check on the status of the hardware and do things
when necessary.  The most important task is shutting down the operating
system cleanly before the UPS runs out of power.  Other programs are
also provided to log UPS status regularly, monitor status through your
web browser, and more.


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

==============================================================================
 DOCUMENTATION
==============================================================================

This file gives an overview of the software.  You should read the man
pages, included example configuration files, and auxiliary documentation
for the parts that you intend to use.


=============================================================================
 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 3493 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 - These programs talk directly to your UPS hardware. 

 - server  - upsd serves data from the 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.  They understand
the protocols and port specifications which define status information
and convert it to a form that upsd can understand.

To configure drivers, edit ups.conf.  For this example, we'll have a UPS
called "sparky" that uses the apcsmart driver and is connected to
/dev/ttyS1.  That's the second serial port on most Linux-based systems.
The entry in ups.conf looks like this:

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

To start and stop drivers, use upsdrvctl.  By default, it will start or
stop every UPS in the config file:

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

However, you can also just start or stop one by adding its name:

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

 EXTRA SETTINGS
 --------------

Some drivers may require additional settings to properly communicate
with your hardware.  If it doesn't detect your UPS by default, check the
driver's man page or help (-h) to see which options are available.

For example, the apcsmart driver allows setting "cable" to "940-0095B".
To use this feature, just add another line to your ups.conf section for
that UPS.

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

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

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

	bcmxcp           - Powerware UPS 9120 'Binary Computer Mode'

	belkin           - Belkin Regulator Pro

	bestferrups801-807

			 - Best FerrUPS 8.01-8.07 models

	bestfortress	 - Very old Best Power Fortress hardware

	bestuferrups	 - Best Power Micro-Ferrups models

	bestups          - Best Power models: (newer, usually beige)

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

	etapro		 - ETA UPS hardware with the "PRO" smart mode

	everups          - EVER Sp. z o.o models

                           - NET *-DPC
                           - AP *-PRO 

	fentonups        - Fenton Technologies models:

	                   - 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 

        hidups           - Experimental driver for USB HID UPSes on Linux

                           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

	isbmex		 - SOLA/BASIC Mexico ISBMEX protocol hardware

	liebert          - Liebert UPStation GXT2 with contact-closure cable

	masterguard	 - Masterguard UPS hardware

	mge-ellipse	 - MGE Ellipse / Ellipse Premium units

	mge-utalk	 - MGE Pulsar ESV/EX, ES+, Evolution units

	microdowell      - Microdowell BBox units

	newapc           - APC smart protocol units

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

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

	oneac		 - Oneac EG and ON equipment

	powercom	 - Trust 425/625
			 - Powercom units
			 - Advice Partner/King PR750
                         - Socomec Sicon Egys 420 VA 

	sec		 - SEC protocol units (various sources)

                         - Clary ST-800

	sms		 - Microlink Manager III

	snmp-ups         - SNMP UPS equipment (RFC 1628)
                           Experimental driver - not built by default.

                           See docs/drivers/snmp-ups.txt for more
                           information.

	powernet	 - APC SNMP devices (e.g. SNMP management cards)
				Requires Net-SNMP and OpenSSL libraries.
				Experimental driver, not built by default.

	tripplite	 - Tripp-Lite SmartUPS units

	victronups	 - IMV/Victron hardware

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

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

If you recently upgraded from 0.45.5 or before, some drivers may be
missing.  This is discussed in the FAQ.

 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 the genericups(8) man page for more information.

There is also a document called generic-ups.txt included with the
source distribution that contains information on adding additional
types to the genericups driver.

 UPS SHUTDOWNS
 -------------

upsdrvctl can also shut down (power down) all of your UPS hardware.

WARNING - if you play around with this command, expect your filesystems
to die.  Don't power off your computers unless they're ready for it.

	/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 drivers to the client 
programs via the network.  It should be run immediately after upsdrvctl
in your system's startup scripts.

upsd should be kept running whenever possible, as it is the only source
of status information for the monitoring clients like upsmon.


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

upsmon provides the essential feature that you expect to find in UPS
monitoring software: safe shutdowns when the power fails.

In the layered scheme of NUT software, it is a client.  It has this
separate section in the documentation since 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 driver, upsd, and upsmon in master mode.

 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
from the drivers.  There are tools for command line access, and a few
special clients which can be run through your web server as CGI
programs.

For more details on specific programs, refer to their man pages.

 UPSC
 ----

upsc is a simple client that will display the values of variables known
to upsd and your UPS drivers.  It will list every variable by default,
or just one if you specify an additional argument.  This can be useful 
in shell scripts for monitoring something without writing your own 
network code.

upsc is a quick way to find out if your driver(s) and upsd are working
together properly.  Just run upsc <ups> to see what's going on, i.e.:

	morbo:~$ upsc localhost
	host: localhost
	MFR: APC
	MODEL: SMART-UPS 700

	[ and so on ]

If you are interested in writing a simple client that monitors upsd,
the source code for upsc is a good way to learn about using the 
upsclient functions.

See the upsc(8) man page for more information.

 UPSLOG
 ------

upslog will write status information from upsd to a file at set
intervals.  You can use this to generate graphs or reports with other
programs such as gnuplot.

 UPSRW
 -----

upsrw allows you to display and change the read/write variables in your
UPS hardware.  Not all devices or drivers implement this, so this may
not have any effect on your system.  

A driver that supports read/write variables will give results like this:

	$ upsrw localhost
	host: localhost
	[SLFTSTINT] "Selftest intervals" (ENUM:4)
	Option: "336"
	Option: "168" SELECTED
	Option: "ON "
	Option: "OFF"

	[ snip ]

On the other hand, one that doesn't support them will print this:

	$ upsrw fenton@gearbox
	host: gearbox
	Error: no read/write variables available

upsrw requires administrator powers to change settings in the hardware.
Refer to upsd.users(5) for information on defining users in upsd.

 UPSCMD
 ------

Some UPS hardware and drivers support the notion of an instant command -
a feature such as starting a battery test, or powering off the load.
You can use upscmd to list or invoke instant commands if your
hardware/drivers support them.

Use the -l command to list them, like this:

	$ upscmd -l localhost
	Instant commands supported on UPS [localhost]:

	ON - Turn on load
	FPTEST - Front panel test

	[ snip ]

upsmon also requires administrator powers to start instant commands.
To define users and passwords in upsd, see upsd.users(5).


==============================================================================
 CGI PROGRAMS
==============================================================================

The CGI programs are clients that run through your web server.  They
allow you to see UPS status and perform certain administrative commands
from any web browser.  Javascript and cookies are not required.

These programs are not installed or compiled by default.  To compile them,
first run 'configure --with-cgi', then 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/

In the event that you need libpng or zlib in order to compile gd, 
they can be found at these URLs:

	http://www.libpng.org/pub/png/pngcode.html

	http://www.gzip.org/zlib/

 ACCESS RESTRICTIONS
 ===================

The CGI programs use hosts.conf to see if they are allowed to talk to a
host.  This keeps malicious visitors from creating queries from your web
server to random hosts on the Internet.

If you get error messages that say "Access to that host is not
authorized", you're probably missing an entry in your hosts.conf.

 UPSSTATS
 ========

upsstats generates web pages from HTML templates, and plugs in status
information in the right places.  It looks like a distant relative of
APC's old Powerchute interface.  You can use it to monitor several
systems or just focus on one.

It also can generate IMG references to upsimage.

 UPSIMAGE
 ========

This is usually called by upsstats via IMG SRC tags to draw either the
utility or outgoing voltage, battery charge percent, or load percent.

 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 upsrw 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 (UPSCLIENT)
==============================================================================

The upsclient.o library can be linked into other programs to give access
to upsd and UPS status information.  Clients like upsc are provided as
examples of how to retrieve data using the upsclient functions.  Other
programs not included in this package may also use this library.  

You may need to do 'make install-misc' to install the upsclient object
and header files in order to build other compatible programs.


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

The version numbers work like this.

  1.0.x - the old stable tree.  No development takes place here.  This
          will appear to stagnate if no bugs are reported, but that's
          actually a good thing.

  1.1.x - the old development tree.  Things are torn apart and rewritten
          to add features and fix design issues.  Once stabilized, this
          becomes 1.2.0.

  1.2.x - the stable tree.  This replaces 1.0.x.

  1.3.x - the next development tree.  Once 1.2.0 has settled down,
          this one will open up for new development work.

Obviously, in terms of the middle number, even = stable and odd =
development.  Fans of the Linux kernel should recognize this numbering
scheme from there.


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

Additional documentation can be found in the docs subdirectory.

If you want to create a new driver, be sure to look at skel.c and
main.c, as all drivers are now built around a common core.  Also see 
new-drivers.txt in the docs directory for more information on what
happens inside the driver core.

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.

Also be sure to read developers.txt, as it explains a lot about the
tree, including some of the functions that are provided for your use.


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

Liebert Corporation supplied serial test boxes and a UPStation GXT2  
with the Web/SNMP card for development of the liebert driver and
expansion of the existing snmp-ups driver.

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

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

Finally, a special thanks to CPS (http://www.citypublicservice.com/)
for providing authentic extended power failures on a regular basis.
Their innovative service provides plenty of opportunities to test
this software and defrost my refrigerator every time there's a
thunderstorm.
