root/trunk/apcupsd-serial.txt

AUTHOR: Hints Author and Owner John M. McSwain <jmcswain@infoave.net>

DATE: 2006-01-04

LICENSE: GNU Free Documentation License Version 1.2
Copyright (c)  2003 John M. McSwain
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation. 
A copy of the license can be found at http://www.gnu.org/copyleft/fdl.html.


SYNOPSIS: Apcupsd power protection for your LFS connected to an APC UPS via serial port.    

DESCRIPTION:
This hint describes the installation of Apcupsd software on an LFS based
computer protected by an American Power Conversion (APC) uinterruptible power
supply connected via serial cable.  The normal software installation analyzes
the sytem to determine a standard linux distribution so that scripts may be
installed to their proper place. Because LFS is nonstandard the installation 
is not completed and left to the user.  This hint describes the steps needed to
complete the software installation on an LFS system.

PREREQUISITES:
This hint will work on any LFS system although the bootscripts may need minor
modifications.  This is especially true of older LFS systems where the 
bootscripts were NOT in the /etc/rc.d/init.d directory.

HINT:

========================
TABLE OF CONTENTS
========================
1 Introduction
2 Software
3 Installation
  3.1 Generic
  3.2 LFS specific
      3.2.1 Boot script
      3.2.2 Poweroff script
      3.2.3 Symlink the scripts
4 Configuration      
5 Conclusion


=================
1. Introduction
=================

Apcupsd is useful for controlling American Power Conversion's (APC)
uninterruptiple power supplies (UPS).  Apcupsd monitors the UPS and during a
power loss, informs the system users of the failure, and if power is not 
restored, safely shuts down the system.  The Apcupsd manual (available on line
at http://www.sibbald.com/apcupsd/manual/index.html or with the software)
provides excellent instructions on installing and configuring the software.
The configure script can identify several standard linux distributions and make
the correct installation. However, as LFS is by design not standard this hint
provides the information to protect an LFS system with an APC UPS connected
via a serial connection using Apcupsd software.

If you are using an APC UPS that connects via USB please see the hint by
Bryan Mason.

The installation of Apcupsd is mostly straightforward until "make install" is
completed. Then the LFS user will see the following series of messages:

"Unknown distribution
You have to manually install apcupsd boot script and
halt script for clean emergency shutdown.
Please contribute your distribution install to apcupsd team.
I'm sorry: you are on your own."

The purpose of this hint is to provide one method of accomplishing the above
actions to get Apcupsd up and running on the LFS "unknown" distribution.


=================
2. Software
=================

The Apcupsd software can currently be found at sourceforge:

http://prdownloads.sourceforge.net/apcupsd/

As of this writing the latest stable release is Apcupsd-3.10.18.


===================
3. Installation
===================

Obtain the source and unpack it in a suitable place such as /usr/src/.
Compiler optimizations can be used with Apcupsd.  See Optimization.txt hint
and the Apcupsd manual for more information.

===================
3.1 Generic
===================
Run the following command:

./configure --prefix=/usr --sbindir=/sbin

This is a basic installation.  If you have a Smartups and wish to have a web
interface to the APC unit's status from your web server see the Apcupsd manual.
You will probably want to run the above commands with additions:

./configure --prefix=/usr --sbindir=/sbin \
 --with-cgi-bin=/srv/www/cgi-bin --enable-cgi

Now run:

make &&
make install

===================
3.2 LFS specific
===================

At the end of the make install you will get the messages listed above in the
introduction.  A bootscript and proper halt script must be manually
installed.

==================
3.2.1 Bootscript
==================

My suggested scripts can be found here:

http://www.linuxfromscratch.org/hints/downloads/attachments/apcupsd-serial/

You may wish to make your own using the template script located in
/etc/rc.d/init.d as a guide.

cd /etc/rc.d/init.d
cp template apcupsd

Now edit the apcupsd file.  Under "start)" have the following lines:

        start)
                boot_mesg "Starting apcupsd power management..."
                # House keeping if this were a restart from powerfail
                rm -f /etc/apcupsd/powerfail
                rm -f /etc/nologin
                loadproc /sbin/apcupsd
                ;;

        stop)
                boot_mesg "Stopping apcupsd power management..."
                killproc /sbin/apcupsd
                ;;

=====================
3.2.2 Poweroff script
=====================

The poweroff script is needed to shutdown the UPS after the system has halted.
(Note: Depending on the UPS this could take a minute or two).  Thus when the 
power returns the UPS will come back on and the system will power up (providing
your atx bios supports powerup).  

Apcupsd for most distributions modifies the existing halt script.  Rather than
that route we are making a separate script called UPSdown.

You may use my script mentioned above, or you can easily make your own using a
text editor and place it in /etc/rc.d/init.d:

#!/bin/sh
# Begin /etc/rc.d/init.d/UPSdown
#
# Script to shutdown UPS after computer shutdown
#
# Symlink in rc0.d after umounting filesystems
#
#
# See if this is a powerfail situation
if [ -f /etc/apcupsd/powerfail ]; then
        echo
        echo "APCUPSD will now power off the UPS"
        echo
        /etc/apcupsd/apccontrol killpower       
        echo
        echo "Verify the UPS shuts down or turn off the system"
        echo
fi
#
# End /etc/rc.d/init.d/UPSdown


=========================
3.2.3 Symlink the scripts
=========================
The apcupsd daemon should be started fairly soon in the boot cycle to provide
protection.  Using the current two digit symlinks, S30 for my system seems
appropriate.  Use your own judgement here.

I stop the daemon rather late in run levels rc1.d and rc6.d, K98.

The UPSdown script should be run immediately prior to the halt script.  If
halt is K99 then UPSdown would be K98.

Run the following:

cd /etc/rc.d/init.d &&
chmod 755 apcupsd UPSdown &&
cd ../rc0.d &&
ln -s ../init.d/UPSdown K98UPSdown &&
cd ../rc1.d &&
ln -s ../init.d/apcupsd K98apcupsd &&
cd ../rc2.d &&
ln -s ../init.d/apcupsd S30apcupsd &&
cd ../rc3.d &&
ln -s ../init.d/apcupsd S30apcupsd &&
cd ../rc4.d &&
ln -s ../init.d/apcupsd S30apcupsd &&
cd ../rc5.d &&
ln -s ../init.d/apcupsd S30apcupsd &&
cd ../rc6.d &&
ln -s ../init.d/apcupsd K98apcupsd


================
4. Configuration
================

Our generic configure in 3.1 above placed the configuration file in
/etc/apcupsd.  This file is called apcupsd.conf.  Please consult the apcupsd
manual to determine the settings for your system and APC model UPS.

================
6. Conclusion
==============
The above steps were an attempt to have you quickly provide APC UPS power
protection to your system using Apcupsd software.  The software allows the
individual user a lot of options depending on his needs and desires.  For
example I use the cgi feature to be able to see the status of my UPS from a
browser.  I use the notification feature to mail the electric company that I
have loss power.  These and other features along with a description of the
workings of Apcupsd are fully described in the Apcupsd manual. 


CHANGELOG:
[2001-06-27]
  * Initial hint.
[2003-02-19]  
  * Updated to current LFS script location (/etc/rc.d/init.d/).
  * Use two digit symlinks versus three.
  * Updated software download location and latest version.
[2003-09-16]
  * Format modified to meet new Hint Format requirements.
[2005-01-04]
  * Updated to apcupsd-3.10.18
  * Modified download location for apcupsd
  * Modified symlinks in run levels
  * Fixed missing last two commands in section 3.2.3 
  * Updated apcupsd startup script to current LFS-6.1.1 style
  * Changed cgi path in section 3.1 configure command from old /home/httpd