nut/INSTALL

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

Also, if your favorite system offers up to date binary packages,
always prefer these over a source installation. Along with the known
advantages of such systems for installation, upgrade and removal, there
are many integration issues that have been addressed.

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

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

 1. Create at least one user and a group for running this software. You
    might call them "ups" and "nut".  The exact names aren'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 be "ups" and "nut" respectively.

    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 and
    --with-group switch to set the user name and group that you created
    above.

	./configure --with-user=ups --with-group=nut

    If you need any other switches for configure, add them here.  For
    example:

    * to build and install USB drivers, add --with-usb (note that you
      need to install libusb development package or files).

    * to build and install SNMP drivers, add --with-snmp (note that
      you need to install libsnmp development package or files).

    * to build and install CGI scripts, add --with-cgi. 

    * to build and install NUT development files (needed to compile
      WMNut and MGE PSP), add --with-lib.

    * to build and install HAL support, add --with-hal.

    See docs/configure.txt or "./configure --help" for the available
    options.

    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

    This will build the NUT client and server programs and the
    selected drivers. It will also build any other features that were
    selected during configuration in step 1. above. 

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

 3. Gain privileges for installing software if necessary.

	su

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


 4. Install the files to a system level directory.

	make install

    This will install the compiled programs and man pages, as well as
    some data files required by NUT. Any optional features selected
    during configuration will also be installed.

    This will also install sample versions of the NUT configuration
    files. 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 0770 /var/state/ups
	chown root: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 0660 /dev/ttyS1
	chown root:nut /dev/ttyS1

    The setup for USB ports is slightly more complicated. Device files
    for USB devices, such as /proc/bus/usb/002/001, are usually
    created "on the fly" when a device is plugged in, and disappear
    when the device is disconnected.  Moreover, the names of these
    device files can change randomly. To set up the correct
    permissions for the USB device, you may need to set up (operating
    system dependent) hotplugging scripts.  Sample scripts and
    information are provided in the scripts/hotplug and
    scripts/udev directories. For most users, the hotplugging scripts
    will be installed automatically by "make install". 

    (If you want to try if a driver works without setting up
    hotplugging, you can add the "-u root" option to upsd, upsmon, and
    drivers; this should allow you to follow the below
    instructions. However, don't forget to set up the correct
    permissions later!).

    NOTE: if you are using something like devfs or udev, 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"

    NOTE: usbhid-ups is a special case and ignores the "port" value.
    You must still set this value, but it does not matter what you set
    it to; you can set "port" to "auto" if you like. If you only own
    one local UBS UPS, the driver will find it automatically. If you
    own more than one UBS UPS, refer to the usbhid-ups(8) man page for
    more information.

    *** 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. By
    default, upsd will only listen to localhost port 3493/tcp. If you want
    to connect to it from other machines, you must specify each interface you
    want upsd to listen on for connections, optionally with a port number.

	LISTEN 127.0.0.1 3493
	LISTEN ::1 3493

    Note: if you run a firewall of some sort, you may have to add rules
    to allow these incoming connections.

    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.

    *** 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 MGE UPS SYSTEMS Ellipse ASR 600 looks
    like this:

	battery.charge: 82
	battery.charge.low: 30
	battery.runtime: 1563
	driver.name: usbhid-ups
	driver.parameter.port: auto
	driver.version: 2.0.3
	driver.version.data: MGE HID 0.8
	driver.version.internal: 0.28
	input.transfer.high: 264.0
	input.transfer.low: 184.0
	outlet.desc: Main Outlet
	outlet.id: 1
	outlet.switchable: 0
	outlet.1.desc: PowerShare Outlet 1
	outlet.1.id: 2
	outlet.1.switch: 0
	outlet.1.switchable: 0
	output.voltage: 230.0
	ups.delay.shutdown: -1
	ups.delay.start: -10
	ups.load: 0
	ups.mfr: MGE UPS SYSTEMS
	ups.model: Ellipse 600
	ups.power.nominal: 600
	ups.serial: AP8F15005
	ups.status: OB DISCHRG

    *** 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. 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
		upsmon master		# or upsmon slave

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

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

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

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

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

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

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

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

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

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

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

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

 7. Start upsmon.

	/usr/local/ups/sbin/upsmon

    If it complains about something, then check your configuration.

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

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

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

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

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

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