Building and Installing Apcupsd

The installation can be made several different ways depending on what system you are running. The basic procedure involves getting a source distribution, running the configuration, rebuilding, and installing. For RedHat systems, apcupsd is available in binary RPM format as well as source RPM format. Please see RedHat RPM Installation below for more details of the RPM installation. For Microsoft Windows systems, there are two forms of binary install (tar file, and setup.exe). Please see Win32 Installation below for more details of the Windows install.

The basic installation from a tar source file is rather simple:

  1. Detar the source code.
  2. cd to the directory containing the source code.
  3. ./configure (with appropriate options as described below)
  4. make
  5. su (i.e. become root)
  6. Stop any running apcupsd
    <system-dependent-path>/apcupsd stop
  7. uninstall any old apcupsd
    This is important since the default install locations have changed.
  8. make install
  9. Start the new apcupsd with:
    <system-dependent-path>/apcupsd start

If all goes well, the ./configure will correctly determine which operating system you are running and configure the source code appropriately. configure currently recognizes Linux (S.u.S.E., RedHat, and Slackware), Sun Solaris, OpenBSD, and CYGWIN operating systems and adapts the configuration appropriately. Check that the configuration report printed at the end of the ./configure process corresponds to your choice of directories, options, and that it has correctly detected your operating system. For systems other than those mentioned above, you may need to do some tweaking.

In general, you will probably want to supply a more complicated configure statement to ensure that the modules you want are built and that everything is placed into the correct directories.

On RedHat, I use the following (all on one line):

CFLAGS="-O2 -Wall" LDFLAGS="-Wall" ./configure -prefix=/usr -sbindir=/sbin --with-cgi-bin=/home/httpd/cgi-bin --enable-cgi

Default Options

By default, make install will install the executable files in /sbin, the manuals in /usr/man, and the configuration and script files in /etc/apcupsd. In addition, if your system is recognized, certain files such as the startup script and the system halt script will be placed in appropriate system directories (usually subdirectories of /etc/rc.d).

Checking the Installation

There are a number of things that you can do to check if the installation (make install) went well. The fist is to check where the system has installed apcupsd using which and whereis. On my RedHat 6.1 system, I get the following (lines preceded with a $ indicate what I typed):

$ which apcupsd
/sbin/apcupsd

and

$ whereis apcupsd
apcupsd: /sbin/apcupsd /etc/apcupsd /etc/apcupsd.conf /etc/apcupsd.status /usr/man/man8/apcupsd.8.gz /usr/man/man8/apcupsd.8

If you find an apcupsd in /usr/sbin, /usr/local/sbin, /usr/lib, or another such directory, it is probably a piece of an old version of apcupsd that you can delete. If you are in doubt, delete it, then rerun the make install to ensure that you haven't deleted anything needed by the new apcupsd. Please note that the files specified above assume the default installation locations.

Final Installation Check

As a final check that the make install went well, you should check your halt script (in /etc/rc.d on SuSE systems, and in /etc/rc.d/init.d on RedHat systems) to see that the appropriate lines have been inserted in the correct place. Modification of the halt script is important so that at the end of the shutdown procedure, apcupsd will be called again to command the UPS to turn off the power. This should only be done in a power failure situation as indicated by the presence of the /etc/powerfail file, and is necessary if you want your machine to automatically be restarted when the power returns. On a RedHat system, the lines containing the # ***apcupsd*** should be inserted just before the final halt command:
# Remount read only anything that's left mounted.
#echo "Remounting remaining filesystems (if any) readonly"
mount | awk '/ext2/ { print $3 }' | while read line; do
    mount -n -o ro,remount $line
done

# See if this is a powerfail situation.                               # ***apcupsd***
if [ -f /etc/apcupsd/powerfail ]; then                                # ***apcupsd***
   echo                                                               # ***apcupsd***
   echo "APCUPSD will now power off the UPS"                          # ***apcupsd***
   echo                                                               # ***apcupsd***
   /etc/apcupsd/apccontrol killpower                                  # ***apcupsd***
   echo                                                               # ***apcupsd***
   echo "Please ensure that the UPS has powered off before rebooting" # ***apcupsd***
   echo "Otherwise, the UPS may cut the power during the reboot!!!"   # ***apcupsd***
   echo                                                               # ***apcupsd***
   sleep 2d                                                           # ***apcupsd***
   exit 0                                                             # ***apcupsd***
fi                                                                    # ***apcupsd***

# Now halt or reboot.
echo "$message"
if [ -f /fastboot ]; then
 echo "On the next boot fsck will be skipped."
elif [ -f /forcefsck ]; then
 echo "On the next boot fsck will be forced."
fi

The above pertains to RedHat systems only. There are significant differences in the procedures on each system, as well as the location of the halt script. Also, the information that is inserted in your halt script varies from system to system. Other systems such as Solaris require you the make the changes manually, which has the advantage that you won't have any unpleasant surprises in your halt script should things go wrong. Please consult the specific system dependent README files for more details.

Configure Options

The following command line options are available for configure to customize your installation.

-prefix=<path>
This defines the directory for the non-executable files such as the manuals. The default is /usr.
-sbindir=<path>
This defines the directory for the executable files such as apcupsd. The default is /sbin. You may be tempted to place the executable files in /usr/sbin or /usr/local/sbin. Please use caution here as these directories may be unmounted during a shutdown and thus may prevent the halt script from calling apcupsd to turn off the UPS power. Though your data will be protected, in this case, your system will probably not be automatically rebooted when the power returns.
--enable-powerflute
This option enables the building of the powerflute executable, which is a ncurses based program to monitor the UPS. This program is not necessary for the proper execution of apcupsd.
--enable-cgi
This enables the building of the CGI programs that permit Web browser access to apcupsd data. This option is not necessary for the proper execution of apcupsd.
--with-cgi-bin=<path>
The with-cgi-bin configuration option allows you to define the directory where the cgi programs will be installed. The default is /etc/apcupsd, which is not necessarily what you want.

Recommended Options for most Systems

For most systems, we recommend the following options:

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

and you can optionally build and install the CGI programs as follows:

./configure -prefix=/usr -sbindir=/sbin --enable-cgi --with-cgi-bin=/home/httpd/cgi-bin

Compilers and Options

Some systems require unusual options for compilation or linking that the ./configure script does not know about. You can specify initial values for variables by setting them in the environment. Using a Bourne-compatible shell, you can do that on the command line like this:

CFLAGS="-O2 -Wall" LDFLAGS= ./configure

Or on systems that have the env program, you can do it like this:

env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure

Or for example on the Sun Solaris system, you can use:

setenv CFLAGS -xO2

setenv LDFLAGS -O

./configure

Operating System Specifics

Alpha
OpenBSD
RedHat
SuSE
Solaris
Windows

Alpha

The Alpha V4.0 version of apcupsd builds without compiler errors with gcc version 2.95.2. It is unlikely that the native Alpha compiler will work because of varargs differences. Unless you are a system guru, we recommend that you connect your UPS to the second serial port /dev/tty01 to avoid conflicts with the console device.
DEVICE /dev/tty01
In addition, you should ensure serial port lock file in apcupsd.conf is defined as:
LOCKFILE /var/spool/locks

Unlike the Linux systems, the system halt routine is located in /sbin/rc0, so after the make install, please check that this file has been correctly updated.

The start/stop script can be found in:

/sbin/init.d/apcupsd

OpenBSD

Ensure that you read the distributions/openbsd/README file before running apcupsd. There are some critical differences in how the OpenBSD implemenation operates when the UPS batteries are exhausted. Failure to take this into account may result in the system not being fully halted when power is lost.

SuSE and RedHat Systems

SuSE and RedHat systems are fully supported, and by following the standard installation instructions given above, you should experience few or no problems.

RedHat RPM Installation

For RedHat systems 6.0, 6.1, and 6.2 (and perhaps 7.0, but it is not tested yet), there are binary and source RPMs available. Follow standard procedures for installing them. The binary RPM can be installed with:

rpm -Uhv <release> where <release> is the release to be installed, and is typically something like apcupsd-3.8.0.i386.rpm (or perhaps apcupsd-3.8.0-pre6.i386.rpm for a pre-release).

After installation of the binary RPM, please verify carefully that /etc/rc.d/init.d/halt was properly updated and contains new script lines flagged with ***APCUPSD***. I (Kern) have noted that for some unknown reason, the rpm does not always update the halt script. In that case, simply either reinstall with the --force option, or remove the installation with the -e option, and reinstall.

Since there is no standard location for cgi-bin, the rpm will place the binary CGI programs in the directory /etc/apcupsd/cgi. To actually use them, you must copy or move them to your actual cgi-bin directory, which on many systems is located in /home/httpd/cgi-bin.

Sun Solaris

Solaris users: December 16th, 1999

Please read this before attempting to compile or install the beta software. It contains important information that will make your efforts easier.

If you find bugs, or run into problems that seem to be related to the version of Solaris that you run, please feel free to contact me by email, or through the development mailing list. I'll attempt to help with problems getting the beta running, although I can't promise a quick response.

As always, remember THIS IS A BETA, and as such, MAY CONTAIN BUGS THAT CAN DAMAGE YOUR SYSTEM AND DATA FILES! You must accept all responsibility for running this software. I'd strongly suggest that you do not run this software on a production system until the final release. An unexpected power-off of a running system can be a disaster. As always, make backups of any critical information before you install this software.

Remember, I told you. I'll listen sympathetically if you lose data, but there will be nothing I can do to help you.

Sincerely,
Carl Erhorn <cerhorn@hyperion.com> <apcupsd-devel@ro.com>


Please read the installation instructions given above before continuing on with these Solaris-specific instructions. Then come back and read this file before attempting to build the package.

For building the system, I'd suggest that you run the configure and make processes as your normal UNIX user ID. The make install must be run as root. But if your normal ID has an environment setup for using the c compiler, it's simpler to do that than setup root to have the correct environment.

If you have the Solaris workshop compilers instead of the GCC or EGCS compilers, edit the configure script, find the PATH=... statement, and comment it out. Also comment out the following line where the new path is exported. NOTE: these are not necessary if you have beta3 or higher.

Whichever compiler you do have, please insure that you can execute the compiler from the command line before running configure. If you do not have an environment setup to run the compiler first, configure will fail.

Your normal UNIX user ID must own the source tree directories, and you must have the normal development tools in your path. This includes make, the compiler, the M4 preprocessor, the linker, and ar or ranlib. If the user you are logged in as can compile and link a c program from a source file, then you have all the required tools available.

For the Solaris beta, you are required to install the executables in the /sbin directory. This will probably remain true, as during shutdown, Solaris will unmount almost everything except the root directories. Since the ability to power the UPS off requires access to the executable programs, they need to be in a directory that will never be unmounted. And since they should also be in a directory that normal users cannot get into, /sbin is the perfect choice. If you have a problem with this, and have a suggestion on another way to solve the problem, please let me know.

The way to setup the /sbin directory as the executables directory is to pass configure the '--sbindir=/sbin' argument (without the quotes, of course). No other arguments should be required, and your setup and platform should be detected automatically by configure.

Once you have run configure, you will need to do a 'make'. Once the make has completed with no errors, you must su to root to complete the install. After the su, you may not have a path to the make program anymore. In that case, you should do the 'make install' step as:

/usr/ccs/bin/make install

Once the install completes, you must edit the /sbin/rc0 script as detailed below, then exit from the su'ed shell.

In order to support unattended operation and shutdown during a power failure, it's important that the UPS remove power after the shutdown completes. This allows the unattended UPS to reboot the system when power returns by repowering the system. Of course, you need autoboot enabled for your system to do this, but all Solaris systems have this by default. If you have disabled this on your system, please re-enable it.

To get the UPS to remove power from the system at the correct time during shutdown, i.e., after the disks have done their final sync, we need to modify a system script. This script is /sbin/rc0.

I do not have access to every version of Solaris, but I think this file will be almost identical on every version. You will need to let me know if this is not true.

At the very end of the /sbin/rc0 script, you should find lines just like the following:

# unmount file systems. /usr, /var and /var/adm are not unmounted by umountall
# because they are mounted by rcS (for single user mode) rather than
# mountall.
# If this is changed, mountall, umountall and rcS should also change.
/sbin/umountall
/sbin/umount /var/adm >/dev/null 2>&1
/sbin/umount /var >/dev/null 2>&1
/sbin/umount /usr >/dev/null 2>&1

echo 'The system is down.'

We need to insert the following lines just before the last 'echo':

#see if this is a powerfail situation
if [ -f /etc/apcupsd/powerfail ]; then
	echo 
	echo "APCUPSD will power off the UPS"
	echo
	/etc/apcupsd/apccontrol killpower
	echo
	echo "Please ensure that the UPS has powered off before rebooting"
	echo "Otherwise, the UPS may cut the power during the reboot!!!"
	echo
	exit 0
fi

I have included these lines in a file called rc0.solaris in the distributions/sun subdirectory of the source tree. You can cut and paste them into the /sbin/rc0 file at the correct place, or yank and put them using vi or any other editor. Note that you must be root to edit this file.

You must be absolutely sure you have them in the right place. If your /sbin/rc0 file does not look like the lines shown above, do not modify the file. Instead, email a copy of the file to me, and I will attempt to figure out what you should do. If you mess up this file, the system will not shut down cleanly, and you could lose data. Don't take the chance.

This feature has only been tested with APC SmartUPS models. If you do not have a SmartUPS, you will be one of the first testers to try this feature. Please send me email to let me know if it works with your UPS model, what model you have, and if possible, the event logs located in /etc/apcupsd. I'd be very interested in your results, and would be glad to work with you to get this feature working correctly with all the APC models. A detailed description of the screen output during the shutdown would be very helpful if you see problems.

You will then need to make the normal changes to the /etc/apcupsd/apcupsd.conf file. This file contains the configuration settings for the package. It is important that you set the values to match your UPS model and cable type, and the serial port that you have attached the UPS to. I have used both /dev/ttya and /dev/ttyb with no problems. You should be sure that logins are disabled on the port you are going to use, otherwise you will not be able to communicate with the UPS. If you are not sure that logins are disabled for the port, run the 'admintool' program as root, and disable the port. The 'admintool' program is a GUI administration program, and required that you are running CDE, OpenWindows, or another XWindows program such as KDE.

At this point, you should have a complete installation. The daemon will load automatically at the next boot. Watch for any error messages during boot, and check the event logs in /etc/apcupsd. If everything looks OK, you can try testing the package by removing power from the UPS.

As a beta tester, your input is very helpful in solving problems with the package, and providing suggestions and future directions for the development of the package. We are striving to provide a useful package that works across all platforms, and welcome your feedback.

Best regards, and thanks for your interest and help, The Apcupsd Development Team.

Windows Systems with CYGWIN Installed

If you have a binary release of the Win32 apcupsd, please see the instructions in the Win32 section of this manual.

If you wish to build from the source, and if you have CYGWIN version 1.1.2 and GCC 2.95.2 installed, it is possible to build the Win32 version of apcupsd.

To date, the Win32 version has only been build on a Win98 SR2 system with the above CYGWIN environment and all the available CYGWIN tools loaded. In addition, the builds were done running under the bash shell. As time permits, we will experiment with other enviroments, and if any of you do build it from source, please let us know. The current Win32 build was done with the following CYGWIN packages loaded:

ash-20000627.tar.gz
autoconf-2.13.tar.gz
bash-2.04.1.tar.gz
binutils-20000625.tar.gz
cygwin-1.1.2.tar.gz
diff.tar.gz
fileutils.tar.gz
findutils.tar.gz
gawk-3.0.4.tar.gz
gcc-2.95.2-2.tar.gz
gdb-20000610.tar.gz
grep.tar.gz
gzip.tar.gz
inetutils-1.3.2-4.tar.gz
less.tar.gz
m4.tar.gz
make-3.79-3.tar.gz
man-1.5g-2.tar.gz
patch.tar.gz
sed-3.02-1.tar.gz
shellutils.tar.gz
tar.tar.gz
textutils.tar.gz
time.tar.gz

We recommend that you run the ./configure command with the following options:

./configure -prefix=/apcupsd -sbindir=/apcupsd/bin -sysconfdir=/apcupsd/etc/apcupsd \
        --with-pid-dir=/apcupsd/etc/apcupsd --mandir=/apcupsd --with-cgi-bin=/apcupsd/etc/apcupsd/cgi \
        --with-pid-dir=/apcupsd/etc/apcupsd
After which, you can do a:
make

and to install it:

make install

When linking popup.exe and apcupsd.exe, the following warning message is printed:

/USR/BIN/ld: warning: cannot find entry symbol _WinMainCRTStartup; defaulting to 00401000
This warning causes no harm. If there is some CYGWIN guru out there who knows how to eliminate this error, please contact me at: kern@sibbald.com.

Finally, you should follow the installation instructions in the Win32 Installation section of this document, skipping the part that describes unZipping the binary release.