Network UPS Tools: INSTALL - Russell Kroll <rkroll@exploits.org>

These are the basic steps for compiling and installing this software.  
There are many different programs in here.  More information on what they
do and how they work can be found in the README file, and also in the docs
subdirectory.

Keep in mind that the paths shown for the programs are the default.  Your
install may change them by passing commands to configure.  Also, if you
didn't install this program from source yourself, the paths probably have
a number of differences.  

Build and install
=================

1. Configure the source tree for your system.

	./configure

2. Build the programs, and optionally build the CGI programs.

	make
	make cgi	- OPTIONAL: requires the gd library and a web server

3. Gain privileges for installing software if necessary.

	su

4. Install the files to a system level directory.

	make install
	make install-cgi	- if you built them earlier
	make install-misc	- only required if you plan to build asapm-ups

   If you are packaging this software, then you will probably want to
   use the INSTALLROOT variable to redirect the build into another place,
   i.e.:

	make INSTALLROOT=/tmp/package install

   Note that the default install process creates a directory for the
   state files and sets the ownership on them, so it needs root powers.

5. Start the driver for your hardware.  If you don't know which one to
   run, consult the README file for a mapping of drivers to hardware
   in the "Model information" section.

	/usr/local/ups/bin/<model> /dev/<port>

   If it reports an error message, then figure out what's wrong before
   doing any of the other steps in this file.

   Some drivers require additional switches to start certain kinds of
   hardware.  Call the driver with -h for more information.

6. Edit config files in /usr/local/ups/etc

   Be sure to create an entry for your UPS in ups.conf.  If your driver
   does not need any special switches, then it should resemble this:

	[myupsname]
		driver = mydriver
		port = /dev/ttyS1

   If you used any -x options to get your driver started, you can also
   list those in that section.

7. Start the network server.

	/usr/local/ups/sbin/upsd

8. Verify that some data is available.

	/usr/local/ups/bin/upsc localhost	

   There may be a lot of data, but the thing that matters is STATUS.
   If your system is running on line power, you should have OL in that
   field.  Otherwise, you are probably have misconfigured the driver 
   in step 5.

Configuring low-battery shutdowns
=================================

The whole point of UPS software is to bring down the OS cleanly when you
run out of battery power.  Everything else is ultimately eye candy.  To
make sure your system shuts down properly, you will need to perform some
additional configuration and run upsmon.  Here are the basics:

1. Set up the access levels in upsd.conf, including a password.

   See docs/access.txt for the explanation of the ACL/ACCESS system.

2. Edit upsmon.conf, and put in that password.

3. Restart upsd to make the change take effect, then start upsmon

4. Look for messages in the syslog to indicate success.  It should look
   something like this:

	May 29 01:11:27 mybox upsmon[102]: Startup successful
	May 29 01:11:28 mybox upsd[100]: Client 10.1.1.1 logged into UPS [myups]

5. Optional, but desirable: edit your shutdown scripts to power down the
   UPS after the filesystems are remounted read-only.  This is the -k
   argument which is described in the shutdown documentation.

For more details, see the README file and the shutdown.txt document.
