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

    Be sure the new user is a member of the new group!  If you forget to
    do this, you will have problems later on when you try to start upsd.

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

  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 would like sample versions of the configuration files to
    be installed, use the install-conf target:

	make install-conf

    Sample files are installed with names like ups.conf.sample so they
    will not overwrite any existing real config files you may have 
    created.

    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
	make DESTDIR=/tmp/package install-conf

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

 5. Create the state path directory for the driver(s) and server to use
    for storing UPS status data and other auxiliary files, and make it
    owned by the user you created.

	mkdir -p /var/state/ups
	chmod 0700 /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.  On FreeBSD, that would be cuaa1.  Serial ports
    vary greatly, so yours may be called something else.

	chmod 0600 /dev/ttyS1
	chown nut:nut /dev/ttyS1

    NOTE: if you are using something like devfs, make sure these
    permissions stay set across a reboot.  If they revert to the old
    values, your drivers may fail to start.

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

 7. Create one section per UPS in /usr/local/ups/etc/ups.conf

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

    Once you have picked a driver, create a section for your UPS in
    ups.conf.  You must supply values for "driver" and "port".

    Some drivers may require other flags or settings.  The "desc" value
    is optional, but is recommended to provide a better description of
    what your UPS is supporting.

    A typical UPS without any extra settings looks like 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

    Make sure the driver doesn't report any errors.  It should show a
    few details about the hardware and then enter the background.  You
    should get back to the command prompt a few seconds later.  For
    reference, a successful start of the belkin driver looks like this:

	# /usr/local/ups/bin/upsdrvctl start
	Network UPS Tools - UPS driver controller 1.5.12
	Network UPS Tools - Belkin Smart protocol driver 0.21 (1.5.12)
	Detected F6C525-SER on /dev/cuaa0
	#

    If the driver doesn't start cleanly, make sure you have picked the
    right one for your hardware.  You might need to try other drivers
    by changing the "driver=" value in ups.conf.

    Be sure to check the driver's man page to see if it needs any extra
    settings in ups.conf to detect your hardware.

    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 (step 5).

    After making changes, try step 6 again.

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

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

 9. Configure upsd, which serves data from the drivers to the clients.

    First, edit upsd.conf to allow access to your client systems.
    A minimal configuration which allows localhost to read status
    data (and nothing else) looks like this:

	ACL all 0.0.0.0/0
	ACL localhost 127.0.0.1/32

	ACCEPT localhost
	REJECT all

    If you have other hosts or networks which will need to talk to
    upsd, you should create ACL and ACCEPT directives for them.

    Next, create upsd.users.  For now, this can be an empty file.
    You can come back and add more to it later when it's time to 
    configure upsmon or run one of the management tools.

    Do not make either file world-readable, since they both hold
    access control data and passwords.  They just need to be readable by
    the user you created in the preparation process.

    The suggested configuration is to chown it to root, chgrp it to the
    group you created, then make it readable by the group.

	chown root:nut upsd.conf upsd.users
	chmod 0640 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

    Make sure it is able to connect to the driver(s) on your system.
    A successful run looks like this:

	# /usr/local/ups/sbin/upsd
	Network UPS Tools upsd 1.5.12
	Connected to UPS [belkin]: belkin-cuaa0
	Synchronizing...done
	# 

    upsd prints dots while it waits for the driver to respond.  Your
    system may print more or less depending on how many drivers you
    have and how fast they are.

    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.  You must fix this before
    going on to the next step.

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

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

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

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

    You should see just one line in response:

	OL

    OL means your system is running on line power.  If it says something
    else (like OB - on battery, or LB - low battery), your driver was 
    probably misconfigured in step 7.  If you reconfigure the driver,
    use 'upsdrvctl stop' to stop it, then start it again in step 8.

    If upsc says "access denied", then your upsd.conf probably doesn't
    have a good ACL/ACCEPT definition for your host.  Go back to step
    9 and fix it.  If you reconfigure upsd, you must either stop and
    restart it, or tell it to reload (upsd -c reload).

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

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

12. Look at all of the status data which is being monitored.

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

    What happens now depends on the kind of UPS and driver you have.
    In the list, you should see ups.status with the same value you got
    above.  A sample run on a Belkin Regulator Pro looks like this:

	battery.charge: 100
	battery.temperature: 048
	battery.voltage: 13.9
	driver.name: belkin
	driver.parameter.port: /dev/cuaa0
	driver.version: 1.5.12
	driver.version.internal: 0.21
	input.frequency: 59.9
	input.transfer.high: 127.6
	input.transfer.low: 96.6
	input.voltage: 119.0
	output.frequency: 59.9
	output.voltage: 119.0
	ups.firmware: 001
	ups.load: 018
	ups.mfr: BELKIN
	ups.model: F6C525-SER
	ups.status: OL
	ups.temperature: 048

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

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

13. 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.  Then use it in an ACCEPT line to allow that host to monitor
    the UPS.  This will let upsmon connect to upsd.

    Assuming a host called mybox with the IP address of 192.168.1.50,
    the configuration looks like this:

	ACL mybox 192.168.1.50/32
	ACCEPT mybox

    You probably have other ACL and ACCEPT/REJECT lines, so be sure this
    ACCEPT happens above any REJECTs which may match this client.  Most 
    users have a "REJECT all" at the bottom.  Here's an example which 
    grants access to localhost and mybox, then rejects anything else.

	ACL all 0.0.0.0/0
	ACL localhost 127.0.0.1/32
	ACL mybox 192.168.1.50/32

	ACCEPT localhost
	ACCEPT mybox
	REJECT all

    Note: if you run a firewall of some sort, you may have to add a rule
    to allow this connection.  upsd runs on port 3493/tcp by default.

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

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

 2. Create a upsd user for upsmon to use while monitoring this UPS.

    Edit upsd.users and create a new section.  upsmon will connect
    to upsd and use this user name (in brackets) and password to
    authenticate.  This example is for a user called "monuser":

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

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

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

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

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

 4. Set the POWERDOWNFLAG location for upsmon.

    In upsmon.conf, add a POWERDOWNFLAG directive with a filename.
    upsmon will create this file when the UPS needs to be powered off
    during a power failure when low battery is reached.

    We will test for the presence of this file in a later step.

	POWERDOWNFLAG /etc/killpower

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

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

 5. Secure upsmon.conf.

    The recommended setting is to have it owned by root:nut, then
    make it readable by the group and not world.  This file contains
    passwords that could be used by an attacker to start a shutdown,
    so keep it secure.

	chown root:nut upsmon.conf
	chmod 0640 upsmon.conf

    This step has been placed early in the process so you secure this
    file before adding sensitive data in the next step.

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

 6. Create a MONITOR directive for upsmon

    Edit upsmon.conf and create a MONITOR line with the UPS definition
    (<upsname>@<hostname>), username and password from step 2, and
    the master or slave setting.

    If it's the master (i.e., it's connected to this UPS directly):

	MONITOR myupsname@mybox 1 monuser mypass master

    If it's just monitoring this UPS over the network, and some other
    system is the master:

	MONITOR myupsname@mybox 1 monuser mypass slave

    The number "1" here is the power value.  This should always be set
    to 1 unless you have a very special (read: expensive) system with
    redundant power supplies.  See big-servers.txt and data-room.txt.

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

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

 7. Define a SHUTDOWNCMD for upsmon.

    Still in upsmon.conf, add a directive that tells upsmon how to
    shut down your system.  This example seems to work on most systems:

	SHUTDOWNCMD "/sbin/shutdown -h +0"

    Notice the presence of "quotes" here to keep it together.

    If your system has special needs, you may want to set this to
    a script which does local shutdown tasks before calling init.

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

 8. Start upsmon.

	/usr/local/ups/sbin/upsmon

    If it complains about something, then check your configuration.

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

 9. 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@192.168.50.1
	logged into UPS [myupsname]

    Any errors seen here are probably due to an error in the config
    files of either upsmon or upsd.  You should fix them before
    continuing.

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

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

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

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

		sleep 120

		# uh oh... the UPS power-off failed
		# you probably want to reboot here so you don't get stuck!
		# *** see the section on power races in shutdown.txt! ***
	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.