$Id$

README file for the ZEDAT UPS Daemon (ZUPS)
===========================================


OVERVIEW
--------

The ZEDAT UPS Daemon (ZUPS) allows for monitoring the state of one or more
UPS devices using SNMP and executing user-specified commands in case of
power outage, such as e-mail or pager notifications and controlled remote
host shutdowns.  If the monitored UPS devices are running on battery, the
shutdown commands are executed for an arbitrary number of remote hosts,
optionally with some delay specified for each host.  Additionally, ZUPS
can be configured to ignore these delays and run the specified commands
immediately if the UPS devices are running out of battery power.  Custom
plugins can easily be added in order to perform arbitrary other checks.
ZUPS should compile and run on any recent UNIX(-like) operating system.


PREREQUISITES
-------------

Net-SNMP 5.0.5 or newer is required for running ZUPS.  Apart from that,
the Net-SNMP header files (often found in some separate Net-SNMP "devel"
package) and an ANSI C compiler plus the usual build tools (such as
make(1)) are needed in order to install ZUPS from source.  See the
Net-SNMP homepage for more information and downloads:

	http://www.net-snmp.org/


INSTALLATION
------------

In most cases, the following three commands should do:

	./configure
	make
	make install

By default, this will install ZUPS to the appropriate subdirectories of
"/usr/local".  Therefore, you'll normally need superuser privileges when
invoking "make install".

The ZUPS installation can be customized by setting environment variables
and/or passing options to "./configure", such as "--prefix=PATH" for
installing ZUPS to subdirectories of "PATH" instead of "/usr/local".  If
the Net-SNMP library is installed to some unusual location or if you want
to specify one out of multiple installed Net-SNMP versions, you can tell
"./configure" where to find the library using "--with-net-snmp=PATH",
where "PATH" is either the Net-SNMP installation prefix or the full path
to the "net-snmp-config" script provided with Net-SNMP.  By default, ZUPS
uses the pidfile "/var/run/zupsd.pid".  In order to specify a different
default pidfile, use "--with-pidfile=PATH", where "PATH" is the pidfile
directory or file path.  For a full list of options and environment
variables, run "./configure --help".  See the file "INSTALL" for details.


CONFIGURATION AND USAGE
-----------------------

ZUPS is configured using the zupsd.conf(5) and zupsd-hosts(5) files,
examples are installed by "make install" (if these files don't exist
already).  See the zupsd.conf(5) manual page for details.  Please test
your configuration using "zupsd -t" (see zupsd(8) for usage details).  If
everything looks fine, a script such as "zupsd-init" (which is provided
with this package) could be used in order to start/stop ZUPS, possibly
during system boot/shutdown.


DOCUMENTATION
-------------

The file "HOWTO" gives a brief description of how to install, configure
and use ZUPS for shutting down remote hosts via SSH in case of power
outage.  Some notes on how to run ZUPS without superuser privileges are
also included.  Detailed information regarding the build and installation
process can be found in the file "INSTALL".  For usage and configuration
documentation, see the zupsd(8) and zupsd.conf(5) manual pages.  The
command "zupsd -h" spits out a short summary of the available command line
options.  For each release, important feature and bugfix additions are
listed in the file "NEWS".  Features which are planned for future releases
are added to the "TODO" file.  See the file "COPYING" for the ZUPS
license.


COPYRIGHT AND AUTHOR
--------------------

Copyright (c) 2005, 2006 Freie Universitaet Berlin.
All rights reserved.

ZUPS is written by Holger Weiss <holger@ZEDAT.FU-Berlin.DE>.

# vim: set js tw=74:
