Installation instructions

Network UPS Tools: INSTALL

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

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

  Prepare your system
  ===================

 1. Create at least one user and a group for running this software.
    You might call it "nut" or "ups".  The exact name isn't important as
    long as you are consistent.

    The process for doing this varies from one system to the next, and
    explaining how to add users is beyond the scope of this document.

    For the purposes of this document, the user name and group name 
    will both be "nut".

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

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


 1. Configure the source tree for your system.  Add the --with-user
    switch to set the user name that you created above.  If you need
    any other switches for configure, add them here.

	./configure --with-user=nut

    If you alter paths with additional switches, be sure to use those
    new paths while reading the rest of the steps.    

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

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

 5. Create a directory for the driver(s) and server to use for data,
    and make it owned by the user you created.

	mkdir /var/state/ups
	chmod 0600 /var/state/ups
	chown nut.nut /var/state/ups

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

 6. Set ownership data and permissions on your serial or USB ports
    that go to your UPS hardware.  Be sure to limit access to just
    the user you created earlier.

    These examples assume the second serial port (ttyS1) on a typical
    Slackware system.  Serial port device names vary greatly, so yours
    may be quite different.

	chmod 0600 /dev/ttyS1
	chown nut.nut /dev/ttyS1

    NOTE: if you are using something like devfs, make sure these
    permissions do not reset themselves when your system reboots.
    Otherwise, your driver(s) may fail to start.

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

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

    Once you have picked a driver, create an entry for your UPS in
    ups.conf.  If the driver does not need any extra configuration
    options, then it should resemble this:

	[myupsname]
		driver = mydriver
		port = /dev/ttyS1
		desc = "Workstation"

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

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

 8. 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 it says "can't bind /var/state/ups/..." or similar, then your
    state path probably isn't writable by the driver.  Check the
    permissions and mode on that directory.

    After making changes, try step 6 again.

    *** References: man pages: nutupsdrv(8), upsdrvctl(8)

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

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

    At the very least, you need something like this in upsd.conf:

	ACL all 0.0.0.0/0
	ACL localhost 127.0.0.1/32

	ACCESS grant monitor localhost
	ACCESS deny all all

    That much is already in the sample upsd.conf, so just copying that 
    to the proper name should get you started.  You should add 
    additional ACL/ACCESS directives for other hosts/networks that need
    to talk to upsd on this system.

    Note: upsd.conf and upsd.users must not be world-readable, since
    they control access controls and passwords.  They do need to be
    readable by the user you created in the preparation process.

    The suggested configuration is to make it owned by that user,
    mode 0400:

	chown nut.nut upsd.conf upsd.users
	chmod 0400 upsd.conf upsd.users

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

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

10. Start the network server.

	/usr/local/ups/sbin/upsd

    NOTE: if upsd says that it can't connect to a UPS or that the data
    is stale, then your ups.conf is not configured correctly, or you
    have a driver that isn't working properly. 

    Nothing else will work until you fix it.

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

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

11. Make sure that the UPS is providing good status data.

	/usr/local/ups/bin/upsc myupsname@localhost	

    Ignore everything but "ups.status" for now.  If your system is
    running on line power, it should have "OL" in that field. 
    Otherwise, something is wrong with the driver that was configured in
    step 5.

    If upsc says "access denied", then your upsd.conf probably doesn't
    have a good ACL/ACCESS definition for your host.

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

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

12. Edit your startup scripts.

    Make sure upsdrvctl and upsd are run every time your system starts.

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

  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.
    This will allow upsmon to connect to upsd.

	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.  This will
    allow upsmon to coordinate shutdowns with other systems.

	[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. Edit your startup scripts: add upsmon

    Make sure upsmon starts when your system comes up.  Do it after
    upsdrvctl and upsd, or it will complain about not being able to
    contact the server.

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

 8. Edit your shutdown scripts: add upsdrvctl shutdown

    You should configure your system to power down the UPS after the
    filesystems are remounted read-only.  Have it look for the presence
    of the POWERDOWNFLAG (from upsmon.conf), using this as an example:

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

    Be careful: that upsdrvctl command will probably power off your
    machine.  Don't use it unless your system is ready to be halted by
    force.  If you run RAID, be sure the arrays are ready to lose power.
    Your kernel's power-off routines may not execute.

    Make sure that the filesystem(s) holding your UPS drivers and
    configuration details are still mounted when that part of the script
    is run.  You need upsdrvctl, ups.conf, and any drivers for the
    hardware on your system.

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

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.