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 may have changed.
8. make install
9. edit your /etc/apcupsd/apcupsd.conf file if necessary
10. ensure that your halt script is properly updated
11. Start the new apcupsd with:
    <system-dependent-path>/apcupsd start
12. IMPORTANT! Test the installation as outlined in the Testing Chapter of this document.

If all goes well, the ./configure will correctly determine which operating system you are running and configure the source code appropriately. configure currently recognizes the systems listed below in the Operating System Specifics section of this chapter 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. If not, redo the ./configure with the appropriate options until your configuration is correct.

Please note that a number of the ./configure options preset apcupsd.conf directive values in an attempt to automatically adapt apcupsd as best possible to your system. You can change the values in apcupsd.conf at a later time without redoing the configuration process by simply editing the apcupsd.conf file.

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:

CFLAGS="-g -Wall" LDFLAGS="-g -Wall" ./configure \
  --prefix=/usr \
  --sbindir=/sbin \
  --with-cgi-bin=/home/www/sibbald/new/cgi-bin \
  --enable-cgi \
  --with-css-dir=/home/www/sibbald/new/docs/css \
  --with-log-dir=/etc/apcupsd \
  --enable-pthreads \
  --enable-powerflute

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

$ which apcupsd
/sbin/apcupsd

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

Final Installation Check

# 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***
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 purpose of modifying the system halt files is so that apcupsd will be recalled after the system is in a stable state. At that point, apcupsd will instruct the UPS to shut off the power. This is necessary if you wish your system to automatically reboot when the mains power is restored. If you prefer to manually reboot your system, you can skip this final system dependent installation step by specifying the --disable-install-distdir option on the ./configure command (see below for more details).

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.

Please note that if you install from RPMs for a slave machine, you will need to remove the changes that the RPM install script made (similar to what is noted above) to the halt script. This is because on a slave machine there is no connection to the UPS, so there is no need to attempt to power off the UPS. That will be done by the master.

Configure Options

All the available configure options can be printed by entering:

./configure --help

When specifying options for ./configure, if in doubt, don't put anything, since normally the configuration process will determine the proper settings for your system. The advantage of these options is that it permits you to customize your version of apcupsd. If you save the ./configure command that you use to create apcupsd, you can quickly reset the same customization in the next version of apcupsd by simply re-using the same ./configure command.

If you are setting up a master/slave configuration, you will be required to make some modifications to the apcupsd.conf files after the configuration process. For more details on a master/slave setup (two computers powered by the same UPS), please see the Configuration Examples Chapter of this document. In addition, you will find some schematic diagrams of the possible configurations in the Configuration Chapter.

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.

--with-css-dir=<path>

This option allows you to specify where you want apcupsd to put the Cascading Style Sheet that goes with the multimoncss.cgi CGI program.

--enable-pthreads

This option enables pthreads support causing apcupsd to be built as a threaded program rather than forking to create separate processes. apcupsd built in this fashion is more efficient that the standard version being one third the data size and less overhead locking and coping shared memory. This option is highly recommended for Windows builds.

--with-libwrap=<path>

This option when enabled causes apcupsd to be built with the TCP WRAPPER libarary for enhanced security.

In most cases, the <path> is optional since configure will determine where the libraries are on most systems.

--with-nologin=<path>

This option allows you to specify where apcupsd will create the nologin file when logins are prohibited. The default is /etc

--with-pid-dir=<path>

This option allows you to specify where apcupsd will create the process id (PID) file to prevent multiple copies from running. The default is system dependent but usually /var/run.

--with-log-dir=<path>

This option allows you to specify where apcupsd will create the EVENTS and STATUS log files. The default is /etc/apcupsd. This option simply sets the appropriate path in the apcupsd.conf file, which can be changed at any later time.

--with-lock-dir=<path>

This option allows you to specify where apcupsd will create create the serial port lock file. The default is system dependent but usually /var/lock. This option simply sets the appropriate path in the apcupsd.conf file, which can be changed at any later time.

--with-pwrfail-dir=<path>

This option allows you to specify where apcupsd will create the powerfail file when a power failure occurs. The default is system dependent but usually /etc.

--with-serial-dev=<device-name>

This option allows you to specify where apcupsd will look for the serial device. The default is system dependent, but often /dev/ttyS0. This option simply sets the appropriate device name in the apcupsd.conf file, which can be changed at any later time.

--with-nis-port=<port>

This option allows you to specify what port apcupsd will use for the Network Information Server (the CGI programs). The default is system dependent but usually 7000. This option simply sets the appropriate port in the apcupsd.conf file, which can be changed at any later time.

--with-net-port=<port>

This option allows you to specify what port apcupsd will use for the Master and Slave communications. The default is system dependent but usually 6666. This option simply sets the appropriate port in the apcupsd.conf file, which can be changed at any later time.

--with-upstype=<type>

This option allows you to specify the type of UPS that will be connected to your computer. The default is: smartups. This option simply sets the appropriate UPS type in the apcupsd.conf file, which can be changed at any later time.

--with-upscable=<path>

This option allows you to specify what cable you are using to connect to the UPS. The default is: smart. This option simply sets the appropriate UPS cable in the apcupsd.conf file, which can be changed at any later time.

--disable-install-distdir

This option modifies the apcupsd Makefiles disable installation of the distribution (platform) directory. Generally, this used to do a full installation of apcupsd except the final modification of the operating system files (normally /etc/rc.d/halt, etc.). This is useful if your operating system is not directly supported by apcupsd or if you want to run two copies of apcupsd on the same system. This option can also be used by those of you who prefer to manually reboot your system after a power failure or who do not want to modify your system halt files.

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

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

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

Below, you will find a list of Operating Systems for which we have received installation files:

Alpha

DEVICE /dev/tty01

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

Caldera

Debian

You can also find the offical Debian packages on the Debian site.

FreeBSD

HPUX

We have no reports of testing this yet on version 3.8.4, but worked fine on 3.8.1

NetBSD

OpenBSD

RedHat Systems

RedHat RPM Installation

rpm -Uhv <release>

IMPORTANTIf you are doing a binary RPM upgrade, please remove the previous version of apcupsd because for some unknown reason, the rpm does not always update the halt script. To do the upgrade, use the following two commands:

rpm -e apcupsd
rpm -Uhv <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***.

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.

Slackware

SuSE

Sun Solaris

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 testing UPSes can be hazardous to you system, and, APCUPSD MAY CONTAIN BUGS THAT CAN DAMAGE YOUR SYSTEM AND DATA FILES! You must accept all responsibility for running this software. 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, we told you. we'll listen sympathetically if you lose data, but there will be nothing we can do to help you.

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

For building the system, we 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.

Normally, we support the GCC compiler, but we have also attempted to support the Solaris workshop compilers and EGCS compilers. Please be aware that if you do not use GCC, you may experience a few problems.

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.

Before running ./configure, please be sure that you do not have /usr/ucb on your path. This may cause the ./configure to chose the wrong shutdown program. If ./configure detects that /usr/usb is on your path, it will print a warning message. Please follow the advice to avoid shutdown problems.

You will want to install the executables in a directory that remains mounted during the 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 default. However, please be aware that if you want to follow Sun's filesystem conventions you would use the following:

./configure \
   --prefix=/opt/apcupsd \
   --sbindir=/etc/opt/apcupsd/sbin \
   --sysconfdir=/etc/opt/apcupsd \
   --with-cgi-bin=/opt/apcupsd/cgi-bin

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

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.

We do not have access to every version of Solaris, but we believe this file will be almost identical on every version. Please let us 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.'

#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
fi

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. We'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.

Solaris EEPROM Changes

eeprom com1-noprobe=true

or

eeprom com2-noprobe=true

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. NOTE! if you have a simple signaling UPS, please run the first power tests with your computer plugged into the wall rather than into the UPS. This is because simple signaling UPSes have a tendency to power off if your configuration or cable are not correct.

As a user, 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.

Unknown Operating System

Windows Systems with CYGWIN Installed

If you wish to build from the source, and if you have CYGWIN version 1.3.2 and GCC 2.95.3-5 installed, it is possible to build the Win32 version of apcupsd. Note, apcupsd version 3.8.0 as distributed was built with CYGWIN version 1.1.2 but works fine when built and run with CYGWIN 1.1.5. Version 3.8.2 was built with CYGWIN version 1.3.1-1, and versions 3.8.3 and 3.8.4 of apcupsd are built with CYGWIN version 1.3.2. Please don't try any other versions of CYGWIN as there were known problems.

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 environments, and if any of you do build it from source, please let us know. The current CYGWIN environment was loaded using the CYGWIN setup.exe program, downloading ALL the latest binaries and installing them.

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 \
  --enable-pthreads

make

make install

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

/USR/BIN/ld: warning: cannot find entry symbol _WinMainCRTStartup; defaulting to 00401000

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