apcupsd-serial.txt

   1 AUTHOR: Hints Author and Owner John M. McSwain <jmcswain@infoave.net>
   2
   3 DATE: 2006-01-04
   4
   5 LICENSE: GNU Free Documentation License Version 1.2
   6 Copyright (c)  2003 John M. McSwain
   7 Permission is granted to copy, distribute and/or modify this document
   8 under the terms of the GNU Free Documentation License, Version 1.2
   9 or any later version published by the Free Software Foundation.
  10 A copy of the license can be found at http://www.gnu.org/copyleft/fdl.html.
  11
  12
  13 SYNOPSIS: Apcupsd power protection for your LFS connected to an APC UPS via serial port.
  14
  15 DESCRIPTION:
  16 This hint describes the installation of Apcupsd software on an LFS based
  17 computer protected by an American Power Conversion (APC) uinterruptible power
  18 supply connected via serial cable.  The normal software installation analyzes
  19 the sytem to determine a standard linux distribution so that scripts may be
  20 installed to their proper place. Because LFS is nonstandard the installation
  21 is not completed and left to the user.  This hint describes the steps needed to
  22 complete the software installation on an LFS system.
  23
  24 PREREQUISITES:
  25 This hint will work on any LFS system although the bootscripts may need minor
  26 modifications.  This is especially true of older LFS systems where the
  27 bootscripts were NOT in the /etc/rc.d/init.d directory.
  28
  29 HINT:
  30
  31 ========================
  32 TABLE OF CONTENTS
  33 ========================
  34 1 Introduction
  35 2 Software
  36 3 Installation
  37   3.1 Generic
  38   3.2 LFS specific
  39       3.2.1 Boot script
  40       3.2.2 Poweroff script
  41       3.2.3 Symlink the scripts
  42 4 Configuration
  43 5 Conclusion
  44
  45
  46 =================
  47 1. Introduction
  48 =================
  49
  50 Apcupsd is useful for controlling American Power Conversion's (APC)
  51 uninterruptiple power supplies (UPS).  Apcupsd monitors the UPS and during a
  52 power loss, informs the system users of the failure, and if power is not
  53 restored, safely shuts down the system.  The Apcupsd manual (available on line
  54 at http://www.sibbald.com/apcupsd/manual/index.html or with the software)
  55 provides excellent instructions on installing and configuring the software.
  56 The configure script can identify several standard linux distributions and make
  57 the correct installation. However, as LFS is by design not standard this hint
  58 provides the information to protect an LFS system with an APC UPS connected
  59 via a serial connection using Apcupsd software.
  60
  61 If you are using an APC UPS that connects via USB please see the hint by
  62 Bryan Mason.
  63
  64 The installation of Apcupsd is mostly straightforward until "make install" is
  65 completed. Then the LFS user will see the following series of messages:
  66
  67 "Unknown distribution
  68 You have to manually install apcupsd boot script and
  69 halt script for clean emergency shutdown.
  70 Please contribute your distribution install to apcupsd team.
  71 I'm sorry: you are on your own."
  72
  73 The purpose of this hint is to provide one method of accomplishing the above
  74 actions to get Apcupsd up and running on the LFS "unknown" distribution.
  75
  76
  77 =================
  78 2. Software
  79 =================
  80
  81 The Apcupsd software can currently be found at sourceforge:
  82
  83 http://prdownloads.sourceforge.net/apcupsd/
  84
  85 As of this writing the latest stable release is Apcupsd-3.10.18.
  86
  87
  88 ===================
  89 3. Installation
  90 ===================
  91
  92 Obtain the source and unpack it in a suitable place such as /usr/src/.
  93 Compiler optimizations can be used with Apcupsd.  See Optimization.txt hint
  94 and the Apcupsd manual for more information.
  95
  96 ===================
  97 3.1 Generic
  98 ===================
  99 Run the following command:
 100
 101 ./configure --prefix=/usr --sbindir=/sbin
 102
 103 This is a basic installation.  If you have a Smartups and wish to have a web
 104 interface to the APC unit's status from your web server see the Apcupsd manual.
 105 You will probably want to run the above commands with additions:
 106
 107 ./configure --prefix=/usr --sbindir=/sbin \
 108  --with-cgi-bin=/srv/www/cgi-bin --enable-cgi
 109
 110 Now run:
 111
 112 make &&
 113 make install
 114
 115 ===================
 116 3.2 LFS specific
 117 ===================
 118
 119 At the end of the make install you will get the messages listed above in the
 120 introduction.  A bootscript and proper halt script must be manually
 121 installed.
 122
 123 ==================
 124 3.2.1 Bootscript
 125 ==================
 126
 127 My suggested scripts can be found here:
 128
 129 http://www.linuxfromscratch.org/hints/downloads/attachments/apcupsd-serial/
 130
 131 You may wish to make your own using the template script located in
 132 /etc/rc.d/init.d as a guide.
 133
 134 cd /etc/rc.d/init.d
 135 cp template apcupsd
 136
 137 Now edit the apcupsd file.  Under "start)" have the following lines:
 138
 139         start)
 140                 boot_mesg "Starting apcupsd power management..."
 141                 # House keeping if this were a restart from powerfail
 142                 rm -f /etc/apcupsd/powerfail
 143                 rm -f /etc/nologin
 144                 loadproc /sbin/apcupsd
 145                 ;;
 146
 147         stop)
 148                 boot_mesg "Stopping apcupsd power management..."
 149                 killproc /sbin/apcupsd
 150                 ;;
 151
 152 =====================
 153 3.2.2 Poweroff script
 154 =====================
 155
 156 The poweroff script is needed to shutdown the UPS after the system has halted.
 157 (Note: Depending on the UPS this could take a minute or two).  Thus when the
 158 power returns the UPS will come back on and the system will power up (providing
 159 your atx bios supports powerup).
 160
 161 Apcupsd for most distributions modifies the existing halt script.  Rather than
 162 that route we are making a separate script called UPSdown.
 163
 164 You may use my script mentioned above, or you can easily make your own using a
 165 text editor and place it in /etc/rc.d/init.d:
 166
 167 #!/bin/sh
 168 # Begin /etc/rc.d/init.d/UPSdown
 169 #
 170 # Script to shutdown UPS after computer shutdown
 171 #
 172 # Symlink in rc0.d after umounting filesystems
 173 #
 174 #
 175 # See if this is a powerfail situation
 176 if [ -f /etc/apcupsd/powerfail ]; then
 177         echo
 178         echo "APCUPSD will now power off the UPS"
 179         echo
 180         /etc/apcupsd/apccontrol killpower
 181         echo
 182         echo "Verify the UPS shuts down or turn off the system"
 183         echo
 184 fi
 185 #
 186 # End /etc/rc.d/init.d/UPSdown
 187
 188
 189 =========================
 190 3.2.3 Symlink the scripts
 191 =========================
 192 The apcupsd daemon should be started fairly soon in the boot cycle to provide
 193 protection.  Using the current two digit symlinks, S30 for my system seems
 194 appropriate.  Use your own judgement here.
 195
 196 I stop the daemon rather late in run levels rc1.d and rc6.d, K98.
 197
 198 The UPSdown script should be run immediately prior to the halt script.  If
 199 halt is K99 then UPSdown would be K98.
 200
 201 Run the following:
 202
 203 cd /etc/rc.d/init.d &&
 204 chmod 755 apcupsd UPSdown &&
 205 cd ../rc0.d &&
 206 ln -s ../init.d/UPSdown K98UPSdown &&
 207 cd ../rc1.d &&
 208 ln -s ../init.d/apcupsd K98apcupsd &&
 209 cd ../rc2.d &&
 210 ln -s ../init.d/apcupsd S30apcupsd &&
 211 cd ../rc3.d &&
 212 ln -s ../init.d/apcupsd S30apcupsd &&
 213 cd ../rc4.d &&
 214 ln -s ../init.d/apcupsd S30apcupsd &&
 215 cd ../rc5.d &&
 216 ln -s ../init.d/apcupsd S30apcupsd &&
 217 cd ../rc6.d &&
 218 ln -s ../init.d/apcupsd K98apcupsd
 219
 220
 221 ================
 222 4. Configuration
 223 ================
 224
 225 Our generic configure in 3.1 above placed the configuration file in
 226 /etc/apcupsd.  This file is called apcupsd.conf.  Please consult the apcupsd
 227 manual to determine the settings for your system and APC model UPS.
 228
 229 ================
 230 6. Conclusion
 231 ==============
 232 The above steps were an attempt to have you quickly provide APC UPS power
 233 protection to your system using Apcupsd software.  The software allows the
 234 individual user a lot of options depending on his needs and desires.  For
 235 example I use the cgi feature to be able to see the status of my UPS from a
 236 browser.  I use the notification feature to mail the electric company that I
 237 have loss power.  These and other features along with a description of the
 238 workings of Apcupsd are fully described in the Apcupsd manual.
 239
 240
 241 CHANGELOG:
 242 [2001-06-27]
 243   * Initial hint.
 244 [2003-02-19]
 245   * Updated to current LFS script location (/etc/rc.d/init.d/).
 246   * Use two digit symlinks versus three.
 247   * Updated software download location and latest version.
 248 [2003-09-16]
 249   * Format modified to meet new Hint Format requirements.
 250 [2005-01-04]
 251   * Updated to apcupsd-3.10.18
 252   * Modified download location for apcupsd
 253   * Modified symlinks in run levels
 254   * Fixed missing last two commands in section 3.2.3
 255   * Updated apcupsd startup script to current LFS-6.1.1 style
 256   * Changed cgi path in section 3.1 configure command from old /home/httpd