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

   *** Additional info: docs/configure.txt

2. Build the programs

	make

3. Gain privileges for installing software if necessary.

	su

4. Install the files to a system level directory.

	make install
	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 DESTDIR variable to redirect the build into another place,
   i.e.:

	make DESTDIR=/tmp/package install

   The default install process creates a state path directory and sets
   the user, group, and mode, so it needs root powers.  You can still
   do 'make install' as a normal user if the destination paths are
   writable by you, but your state path (normally /var/state/ups) 
   may need some changes before things will work.

5. Create section(s) for your hardware in /usr/local/ups/etc/ups.conf

   Now you must create an entry for your UPS in ups.conf.  If your
   driver does not need any extra configuration options, then it should
   resemble this:

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

   *** Additional info: man pages: ups.conf(5), nutupsdrv(8), plus
                        whatever driver(s) you intend to use.

6. Start the driver(s) for your hardware.

	/usr/local/ups/bin/upsdrvctl start

   If the driver doesn't start cleanly, make sure you're starting the 
   right one for your hardware.  Also check the man page for the
   driver to see if there are any extra values that you can set.
   If you need any of them, add them to your ups.conf and try step 6
   again.

   *** Additional info: man pages: nutupsdrv(8), upsdrvctl(8)

7. Configure the network server.  The files that need your attention are
   upsd.conf and upsd.users.  Sample versions are installed in most cases.

   *** Additional info: man pages: upsd.conf(5), upsd.users(5), upsd(8)

8. Start the network server.

	/usr/local/ups/sbin/upsd

   *** Additional info: man page: upsd(8)

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

   *** Additional info: man page: upsc(8)

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.
   The directives you will need to use are ACL and ACCESS.

   *** Additional info: man pages: upsd(8), upsd.conf(5)

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

   *** Additional info: man pages: upsmon(8), upsmon.conf(5)

3. Make upsd reload its config file ('upsd -c reload' or 'kill -HUP <pid>'),
   or just restart it to make the change take effect.

5. Start upsmon.

6. 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 upsmon[103]: UPS [myups@mybox]: login successful
	May 29 01:11:28 mybox upsd[100]: Client 10.1.1.1 logged into UPS [myups]

6. Optional, but desirable: edit your shutdown scripts to power down the
   UPS after the filesystems are remounted read-only.

   The direct approach is to call <driver> -k <port>, but the most
   consistent way is to use upsdrvctl like this:

	/path/to/upsdrvctl shutdown

   Be careful with that command, as it will probably power off your machine.
   Only use it when your OS is ready to be forcibly halted.

More information can be found in the README file, the shutdown.txt document, 
the upsmon(8) man page and the upsmon.conf(5) man page.
