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

These are the essential steps for compiling and installing this
software, including configuring safe shutdowns when the UPS battery runs
out of power.

There are many programs and other features in this package.  You should
check out the README file and other accompanying documentation to see
how it all works.

The paths shown below are the default values you get by just calling
configure by itself.  If you have used --prefix or similar, things will
be different.  Also, if you didn't install this program from source
yourself, the paths will probably have a number of differences.

Note: by default, your system probably won't find the man pages, since
they install to /usr/local/ups/man.  You can fix this by editing your
MANPATH, or just do this:

	man -M /usr/local/ups/man <man page>

	man -M /usr/local/ups/man upsd.conf

============================================================================
============================================================================
============================================================================

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


 1. Configure the source tree for your system.  If you need additional
    switches to configure, add them here.

	./configure

    *** Reference: 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

    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

    To find out which driver to use, check the "HARDWARE SUPPORT TABLE"
    in the README file, or docs/driver.list.

    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

    *** References: 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.

    After making the changes to ups.conf, try step 6 again.

    *** References: 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.

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

---------------------------------------------------------------------------

 8. Start the network server.

	/usr/local/ups/sbin/upsd

    NOTE: if upsd complains about the data being "stale at startup",
    then you have a driver that isn't working properly.  Nothing else
    will work until you fix it, so don't move on until it's happy.

    *** Reference: 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.

    *** Reference: man page: upsc(8)

============================================================================
============================================================================
============================================================================

  Configuring shutdowns for low battery events
  --------------------------------------------

The whole point of UPS software is to bring down the OS cleanly when you
run out of battery power.  Everything else is just 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. Configure upsd to recognize upsmon.

    First create an ACL in upsd.conf for the host that will be running
    upsmon.  Be sure to grant it monitor privileges with an ACCESS line.

	ACL all 0.0.0.0/0
	ACL mybox a.b.c.d/32
	ACCESS grant monitor mybox
	ACCESS deny all all

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

---------------------------------------------------------------------------

 2. Edit upsd.users, and create a user for upsmon to use.

	[monuser]
		password = mypass
		allowfrom = mybox
		upsmon master		(or upsmon slave)

    *** References: man pages: upsd(8), upsd.users(5)

---------------------------------------------------------------------------

 3. Edit upsmon.conf, and create a MONITOR directive with that host,
    username, and password.

	MONITOR myupsname@mybox 1 monuser mypass master		(or slave)

    Also check the POWERDOWNFLAG to make sure it's what you want.

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

---------------------------------------------------------------------------

 4. Reload upsd.  Depending on your configuration, you may be able to 
    do this without stopping upsd:

	/usr/local/ups/sbin/upsd -c reload

    If that doesn't work (check the syslog), just restart it:

	/usr/local/ups/sbin/upsd -c stop
	/usr/local/ups/sbin/upsd 

    Later: if you want to make reloading work, see the entry in the FAQ
    about starting upsd as a different user.

---------------------------------------------------------------------------

 5. Start upsmon.

	/usr/local/ups/sbin/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 upsd[100]: Client monuser@a.b.c.d logged into UPS [myupsname]

---------------------------------------------------------------------------

 7. Recommended: edit your shutdown scripts to power down the UPS after
    the filesystems are remounted read-only.  Have it refer to your
    POWERDOWNFLAG location from upsmon.conf, like this:

	if (test -f /etc/killpower)
	then
		echo "Killing the power, bye!"
		/usr/local/ups/bin/upsdrvctl shutdown
	fi

    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.

    Also make sure that the filesystem holding your UPS drivers and
    configuration programs are still mounted when that part of the
    script runs.

---------------------------------------------------------------------------

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.
