apcupsd is a complex piece of software, but most of its complexities are meant for dealing with older hardware and operating systems. On current hardware and software getting it running should not be very complicated.

The following is a help guide to the steps needed to get apcupsd set up and running as painlessly as possible.

Please note that due to the lack of Unix USB API standards, the USB code in apcupsd works only on Linux. Drivers for other OSes can be written, but it requires someone with a knowledge of the OS and the USB to do so. (This lack of a Unix USB API interface is one of the big failings of Unix. It occurs in other areas such as the GUI. Many people tout the diversity as an advantage, but it is in fact a weakness.)

The apcupsd maintainers develop it under Red Hat; that port is, accordingly, the most up to date and best tested. There are enough Debian Linux users that that port is also generally pretty fresh. Slackware Linux is also fully supported.

apcupsd has also been ported to FreeBSD, NetBSD, OpenBSD, HP/UX, Solaris, Alpha Unix and the Cygwin Unix emulation under Windows. It is quite likely to work on those systems, though the port may occasionally get stale and require minor tweaking.

In the section called “Operating System Specifics” you'll find operating-system-specific tips for building and configuring apcupsd.

You can generally count on your UPS being supported if it has either an Ethernet-connected SNMP interface or a USB interface with an APC-supplied cable.

The "UPSTYPE Keyword" field is the value you will put in your /etc/apcupsd/apcupd.conf file to tell apcupsd what type of UPS you have. We'll describe the possible values here, because they're a good way to explain your UPS's single most important interface property — the kind of protocol it uses to talk with its computer.

There are three major ways of running apcupsd on your system. The first is a standalone configuration where apcupsd controls a single UPS, which powers a single computer. This is the most common configuration. If you're working with just one machine and one UPS, skip the rest of this section.

Your choices become more interesting if you are running a small cluster or a big server farm. Under those circumstances, it may not be possible or even desirable to pair a UPS with every single machine. apcupsd supports some alternate arrangements.

The second type of configuration is a master/slave configuration, where one UPS powers several computers, each of which runs a copy of apcupsd. The computer that controls the UPS is called the master, and the other computers are called slaves. The master copy of apcupsd communicates with and controls the slaves via an Ethernet connection. This type of configuration may be appropriate for a small cluster of machines. Some example configuration files for the master and the slave machines can be found in the examples directory of the source distribution. The more recent examples are in master.apcupsd.conf and slave.apcupsd.conf.

The third configuration (new with version 3.8.3), is where a single computer controls multiple UPSes. In this case, there are several copies of apcupsd on the same computer, each controlling a different UPS. One copy of apcupsd will run in standalone mode, and the other copy or copies will normally run in master/slave mode. This type of configuration may be appropriate for large server farms that use one dedicated machine for monitoring and diagnostics

Here is a diagram that summarizes the possibilities:

Figure&nspb;&nspb;1.1.&nspb;&nspb;Configuration types.

If you decide to set up one of these more complex configurations, see the Advanced Topics section for details.

You can skip this section if your UPS has an Ethernet or RS232-C interface or you are not running on a Linux kernel. If it has a USB interface, you need to make sure that your USB subsystem can see the UPS. On a Linux system this is easy, just do this from a shell prompt:

cat /proc/bus/usb/devices

This information is updated by the kernel whenever a device is plugged in or unplugged, irrespective of whether apcupsd is running or not. To interpret the codes in this file, please see http://www.linuxhq.com/kernel/v2.4/doc/usb/proc_usb_info.txt.html

You should get some output back that includes something like this from ESR's site, featuring an RS 1000:

T:  Bus=02 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  3 Spd=1.5 MxCh= 0
D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=051d ProdID=0002 Rev= 1.06
S:  Manufacturer=American Power Conversion
S:  Product=Back-UPS RS 1000 FW:7.g3 .D USB FW:g3
S:  SerialNumber=JB0308036505
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 24mA
I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=00 Prot=00 Driver=hid

Note, if on the last line, Driver is listed as Driver=none then you do not have the HID driver loaded or the driver did not attach to the UPS. One common cause is having a Linux kernel older than 2.4.22 (such as a stock RedHat 9 kernel). If this is the case for your system, please upgrade to at least kernel version 2.4.22 and try again. Otherwise, please read further for instructions for other possible courses of action.

Here are two more ample entries from Kern Sibbald. The first features a Back-UPS 350 direct connected USB device:

T:  Bus=01 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=1.5 MxCh= 0
D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=051d ProdID=0002 Rev= 1.00
S:  Manufacturer=American Power Conversion
S:  Product=Back-UPS 350 FW: 5.2.I USB FW: c1 
S:  SerialNumber=BB0115017954
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 30mA
I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=00 Prot=00 Driver=hid
E:  Ad=81(I) Atr=03(Int.) MxPS=   8 Ivl= 10ms

The second features an IOgear USB-to-serial adapter that runs my serial SmartUPS 1000 :

T:  Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#=  4 Spd=12  MxCh= 0
D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=0557 ProdID=2008 Rev= 0.01
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
I:  If#= 0 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=00 Prot=00 Driver=serial
E:  Ad=81(I) Atr=03(Int.) MxPS=  10 Ivl=  1ms
E:  Ad=02(O) Atr=02(Bulk) MxPS=  64 Ivl=  0ms
E:  Ad=83(I) Atr=02(Bulk) MxPS=  64 Ivl=  0ms

Note that the IOgear device is using the serial driver (the I: line) while the Back-UPS 350 is using the hid driver.

In general, if you see your UPS model in the S field, which means Manufacturer=, Product=, and SerialNumber=, and you see hid in the I field (or serial if you are using an IOGear connection), you're done. You can skip the rest of this section and go straight to building and installing.

If it doesn't show, check the obvious things; the UPS must be powered on, and a cable must be properly seated in both the data port of the UPS and one of your machine's USB ports. Many UPSes have phone ports to provide surge protection for phones or modems — make sure you haven't plugged your USB cable into one of those rather than the data port (which will usually be near the top edge of the case.)

Also, ensure that the correct drivers are loaded. Under Linux, you can check this out easily by examining the right file in the /proc system. Here's how you can do that:

esr@grelber$ cat /proc/bus/usb/drivers
         usbdevfs
         hub
 96-111: hiddev
         hid

A USB UPS needs all of these drivers — the USB device filesystem, the USB hub, the Human Interface Device subsystem driver, and the Human Interface Device driver. If you are compiling your own kernel, you want to enable CONFIG_USB, CONFIG_USB_HID, CONFIG_USB_HIDDEV, and CONFIG_USB_DEVICEFS as well as at least one USB Host Controller Driver (CONFIG_USB_UHCI_HCD [2.6.x], CONFIG_USB_UHCI [2.4.x], etc.).

For the IOGear serial USB connection, you need:

usbcore
usbserial
pl2303

Finally, check that appropriate USB devices exist. On a Red Hat system you can do this:

esr@grelber$ ls /dev/usb/h*
/dev/usb/hiddev0   /dev/usb/hiddev12  /dev/usb/hiddev2  /dev/usb/hiddev6
/dev/usb/hiddev1   /dev/usb/hiddev13  /dev/usb/hiddev3  /dev/usb/hiddev7
/dev/usb/hiddev10  /dev/usb/hiddev14  /dev/usb/hiddev4  /dev/usb/hiddev8
/dev/usb/hiddev11  /dev/usb/hiddev15  /dev/usb/hiddev5  /dev/usb/hiddev9

This will tell you that the Human Interface Device nodes, one of which apcupsd will use to talk with the UPS, exist. On other Linuxes the layout will be slightly different; the hiddev devices will usually live in a /dev/usb/hid/ subdirectory. If these devices don't exist, you may need to run <apcupsd-source>/examples/make-hiddev to create them.

Now build and run the hid-ups test program. You do not have to configure and build the rest of apcupsd to do this. To build hid-ups enter:

cd <apcupsd-source>/examples
make hid-ups

There should be no errors. Now assuming that everything has gone well to this point and that you have connected your USB UPS, enter:

./hid-ups

It should print a sample report of the information that it has obtained from your UPS. CAUTION! if you have a 2.4.x Linux kernel do not run two copies of this program at the same time, or your kernel will freeze. The report that is printed should look very similar to the report in <apcupsd-source>/examples/hid-ups.rpt. If the program reports that the device was not found ensure that all the appropriate modules are loaded (as described earlier), then unplug your UPS and plug it back in. This should permit the kernel to recognize the UPS.

If ./hid-ups tells you "No permission, try this as root", you know what to try. If it says "Couldn't find USB UPS device, check your /dev.", then it is very unlikely that apcupsd will work. You probably need to run the script "make-hiddev" before continuing.

If all there things check out and you still can't see the UPS, something is more seriously wrong than this manual can cover — find expert help. If you are unable to list USB devices or drivers, you kernel may not be USB-capable and that needs to be fixed. Please check if your kernel has the three patches listed in the <apcupsd-source>/examples directory. Each of the files ends with the name .patch, and at the current writing they are:

linux-2.4.20-killpower.patch
linux-2.4.20-USB-reject.patch
linux-2.6.0-USB-queue-overflow.patch

For example, RedHat 9 and/or pre-2.4.22 kernels are known to need the linux-2.4.20-USB-reject.patch for APC SmartUPS XL series devices.

There are also a few email files that you can consult in the examples directory for additional information and details.

Installation from source might have to be be done different ways depending on what system you are running. The basic procedure involves getting a source distribution, running the configuration, rebuilding, and installing.

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

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 the section called “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.

Other configuration options can be used to set up the installation of HTML documentation and optional modules, notably the CGI interface that enables the UPS state to be queried via the Web and the optional powerflute curses-based control panel. Still others enable features such as thread support. You will find a complete reference later in this chapter.

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

On Red Hat, a fairly typical configuration command would look like the following:

CFLAGS="-g -O2" LDFLAGS="-g" ./configure \
  --enable-usb \
  --with-serial-dev=/dev/usb/hiddev[0-15] \
  --with-upstype=usb \
  --with-upscable=usb \
  --prefix=/usr \
  --sbindir=/sbin \
  --with-cgi-bin=/var/www/cgi-bin \
  --enable-cgi \
  --with-css-dir=/var/www/docs/css \
  --with-log-dir=/etc/apcupsd \
  --enable-pthreads \
  --enable-powerflute

On other Linux systems, the --with-serial-dev may need to be /dev/usb/hid/hiddev[0-15]. The [0-15] is not a typo, but should be entered exactly as shown. This is because the UPS can change device numbers while it is running. Every time there is a blip or slowdown on the USB line, the kernel will invalidate the UPS connection, then a few moments later, it will reconnect but with a different device number. Not very Unix-like, but that is what happens. This bizarre syntax allows apcupsd to try a range of devices until it finds or re-finds the UPS device.

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

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 Red Hat system, you should get the following (lines preceded with a $ indicate what you type):

$ 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

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.

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 Red Hat 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 Red Hat 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***
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 Red Hat 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.

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.

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

For most systems, we recommend the following options:

./configure --prefix=/usr --sbindir=/sbin --enable-usb \
            --enable-pthreads

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

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

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 -O2
setenv LDFLAGS -O
./configure

You can get a listing of all available options by doing:

./configure --help

or simply see the previous section of this manual.

With the exception of Linux SUSE and Linux Red Hat systems used by the developers, we rely on users to help create installation scripts and instructions as well as to test that apcupsd runs correctly on their system. As you can imagine, most of these people are system administrators rather than developers so they are very busy and don't always have time to test the latest releases. With that in mind, we believe that you will find that a lot of very valuable work has been already done to make your installation much easier (and probably totally automatic).

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

DEVICE /dev/tty01

LOCKFILE /var/spool/locks

/sbin/init.d/apcupsd

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

/usr/ccs/bin/make install

# 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

eeprom com1-noprobe=true

eeprom com2-noprobe=true

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

Once you have installed apcupsd, either from a binary package or by building from source, your next step should be to inspect your /etc/apcupsd/apcupsd.conf file to make sure it is valid.

You can read the complete reference on configuration directives, but if you are setting up a normal standalone configuration you should only need to check (and possibly fix) the first three items listed below.

Your UPSTYPE should be the UPS's protocol type: dumb, apcsmart, usb, net, or snmp. Your UPSCABLE should be the type of cable you are using. You should have gotten both from the table of types; usually they will both be the string "usb".

If you have a USB device, it is better not to specify a DEVICE directive by commenting it out. Apcupsd will automatically search for your device in the standard places. If you specify a DEVICE, it should be the name of the device (or device range) that apcupsd is to use to communicate with the UPS. If you're using a USB UPS under Linux, you may leave the device name field blank and apcupsd will search all the standard locations for the UPS. You may also explicitly specify the device location as either /dev/usb/hid/hiddev[0-15] (on non-Red-Hat systems) or /dev/usb/hiddev[0-15] (on Red Hat systems).

Note that you should enter "/dev/usb/hiddev[0-15]" literally as shown. The "[0-15]" expression tells apcupsd to search all hiddev devices until it finds a UPS. You can restrict the search to a subset of devices by using something like "[0-4]", but keep in mind this will limit apcupsd's ability to locate the UPS if the kernel relocates it to a differentdevice node.

If the first time you execute apcupsd, you get a message to the effect that the Apcupsd USB driver is missing, it means that you most likely forgot to put --enable-usb on your ./configure command line. If you loaded apcupsd from an rpm file, you may have selected the wrong one -- please ensure that the word usb appears in the rpm package name.

The next chapter of this manual provides you with the essential characteristics of each main type of configuration file. After those elements are correct, apcupsd should run, and then it is only a matter of customization of your setup.

The final consideration for a automatic reboot after a full power down is to ensure that your computer will automatically reboot when the power is restored.

This is not the normal behavior of most computers as shipped from the factory. Normally after the power is cut and restored, you must explicitly press a button for the power to actually be turned on. You can test your computer by powering it down; shutting off the power (pull the plug); then plugging the cord back in. If your computer immediately starts up, good. There is nothing more to do.

If your computer does not start up, manually turn on the power (by pressing the power on button) and enter your computer's SETUP program (often by pressing DEL during the power up sequence; sometimes by pressing F10). You must then find and change the appropriate configuration parameter to permit instant power on.

Normally, this is located under the BOOT menu item, and will be called something such as Restore on AC/Power Loss or Full-On. The exact words will vary according to the ROM BIOS provider. Generally you will have three options: Last State, Power On, and Power Off. Although Last State should normally work, we recommend setting your computers to Power On. This means that whenever the power is applied they are on. The only way to shut them off is to pull the plug or to have a special program that powers them off (/sbin/poweroff on Linux systems).

If after making all the changes suggested above, you cannot get your computer to automatically reboot, you might examine your halt script (/etc/rc.d/init.d/halt in the case of Red Hat Linux) and see if the final line that performs the halt or reboot contains the -p option for powering down the computer. It should not with the logic used by apcupsd, but if it does, the -p option could cause your computer to power off while the UPS is still suppling power (i.e. before the UPS kills the power). Depending on the setting of your BIOS, it may prevent your computer from restarting when the power returns. As already mentioned, this should not apply, but in case of problems it is worth a try.

The simplest way to invoke apcupsd is from the command line by entering:

/sbin/apcupsd

To do so, you must be root. However, normally, you will want apcupsd started automatically when your system boots. On some systems with installation support (e.g. SUSE and Red Hat), the installation procedure will create a script file that you will be automatically invoked when your system reboots. On other systems, you will have to invoke apcupsd from your rc.local script.

On Red Hat systems, this script file that automatically invokes apcupsd on system start and stops is: /etc/rc.d/init.d/apcupsd

To start apcupsd manually (as you will probably do immediately following the installation), enter the following:

/etc/rc.d/init.d/apcupsd start

To understand how this file is automatically invoked at system startup and shutdown, see the man pages for chkconfig(8).

On SUSE systems, the script file that automatically invokes apcupsd on system start and stops is /etc/rc.d/apcupsd

To start apcupsd manually (as you will probably do immediately following the installation), enter the following:

/etc/rc.d/apcupsd start

Normally, when properly installed, apcupsd will be started and stopped automatically by your system. Unfortunately, the details are different for each system. Below, we give the commands for selected systems. Alternatively, there are simple stopapcupsd and startapcupsd scripts in the examples directory, or you can modify one of the scripts in the distributions directory to meet your needs.

To stop apcupsd you can do the following:

On Red Hat systems:

/etc/rc.d/init.d/apcupsd stop

On SUSE systems:

/etc/rc.d/apcupsd stop

Please see the Testing Apcupsd chapter for more details on insuring that apcupsd is running properly.

If you have a USB UPS, and you have apcupsd version 3.10.7 or higher, the essential elements of your apcupsd.conf file should look like the following:

## apcupsd.conf v1.1 ##
UPSCABLE usb
UPSTYPE usb
#DEVICE
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable

Notice that we have not specified a device. In doing so, apcupsd will try all the well know USB ports.

If you have more than one device, you will need to specify each one individually. If you have a RedHat system, and know what you are doing, you may want a DEVICE specification as follows:

DEVICE /dev/usb/hiddev[0-15]

If you have used the make-hiddev that is in the examples directory of the source, you will want to specify a DEVICE as follows:

DEVICE /dev/usb/hid/hiddev[0-15]

Please use the explicit specifications of a device only if your know exactly what you are doing. In general, it is much easier to let apcupsd find the device itself.

Note that you should enter "/dev/usb/hiddev[0-15]" literally as shown. The "[0-15]" expression tells apcupsd to search all hiddev devices until it finds a UPS. You can restrict the search to a subset of devices by using something like "[0-4]", but keep in mind this will limit apcupsd's ability to locate the UPS if the kernel relocates it to a differentdevice node.

If you have a Smart UPS using the cable supplied by APC, or you build a CUSTOM SMART cable outlined in the cables chapter, a very simple configuration file would look like the following:

## apcupsd.conf v1.1 ##
UPSCABLE smart
UPSTYPE smartups
DEVICE /dev/ttyS0
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable

Normally you would have many more configuration directives to completely customize your installation, but this example shows you the minimum required.

If you have a simple signaling or dumb UPS such as a BackUPS, you will need to know exactly what cable you have and specify it on the UPSCABLE directive. Please see the list of UPSes versus cables in the beginning of this document for more information.

## apcupsd.conf v1.1 ##
UPSCABLE (number of cable you have)
UPSTYPE dumb
DEVICE /dev/ttyS0
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable

Normally you would have many more configuration directives to completely customize your installation, but this example shows you the minimum required.

You have a Smart UPS using the cable supplied by APC and you want it to act as a master for another computer, which is powered by the same UPS. A very simple configuration file would look like the following:

## apcupsd.conf v1.1 ## 
UPSCABLE smart
UPSTYPE smartups
DEVICE /dev/ttyS0
LOCKFILE /var/lock
UPSCLASS netmaster
UPSMODE net
NETTIME 10
NETPORT 6666
SLAVE slave1.mynetwork.com
SLAVE slave2.mynetwork.com

Note, the main difference from the stand alone configuration is that you have specified UPSCLASS netmaster and UPSMODE net. In addition, you have specified one or more slave machines.

You have a Smart UPS using the cable supplied by APC that is connected to the master machine configured above. This slave machine has no serial port connection to the UPS, but is powered by the same UPS as the master. A very simple configuration file would look like the following:

## apcupsd.conf v1.1 ## 
UPSCABLE ether
UPSTYPE smartups
LOCKFILE /var/lock
UPSCLASS netslave
UPSMODE net
NETPORT 6666
MASTER master.mynetwork.com

The main difference from the master configuration is that you have specified UPSCABLE ether and UPSCLASS netslave. In addition, you have specified a single controlling master.

In this configuration, the shutdown will be initiated by the master. It is also possible to specify BATTERYLEVEL, MINUTES, and TIMEOUT configuration directives in the Slave machine that will cause the slave to shutdown before the master. This can often be useful if the slave is less important than the master and you wish to reduce battery power consumption so that the master can remain up longer during a power outage.

It is also possible to have a Master/Slave configuration where the Slave is powered by a different UPS (or any other power source), but is nevertheless controlled (i.e. shutdown) by the master. The setup would be identical to the Master/Slave configuration files shown above. The only difference is where the slave actually receives its power. In effect, apcupsd does not know or care where the power really comes from.

As opposed to the master/slave mode demonstrate above, you can turn any computer into a slave by configuring with the NIS network driver turned on --enable-net. Running in this configuration, you can use any computer with apcupsd running the Network Information Server (NIS) as the master. The slave simply uses the NIS information to decide when to shutdown. This is a much simpler mode than the older master/slave code mentioned above.

## apcupsd.conf v1.1 ## 
UPSCABLE ether
UPSTYPE net
LOCKFILE /var/lock
DEVICE server-network-address:3551
UPSCLASS standalone
UPSMODE disable

where on the DEVICE directive you replace the server-network-address with the fully qualified domain name or IP address of a machine running apcupsd with NIS enabled (and normally, but not required, connected to a UPS). The :3551 that follows the server address is the port to use. The default is 3551, but older versions of apcupsd used port 7000.

Please do not confuse this with a master/slave network configuration that is described above. This is a master/slave setup, but much simpler (the master does not know about the slaves), and any NIS server, even a slave, can act as a server to a slave that listens to it.

This mode works principally by reading the STATFLAG record that is sent by the NIS (present in the output of apcaccess). The low 16 bits are the standard APC status flag, and the upper 16 bits represent the internal state of apcupsd, so the slave can see when the power fails and know when to shutdown.

After you start apcupsd, execute the following command:

ps fax

or the equivalent for your system. If you are running on Linux and using the fork()ing version of apcupsd, you should something similar to the following output.

4492 ?        S      0:00 apcmain       -f /etc/apcupsd/apcupsd.conf
4496 ?        S      0:00  \_ apcser        -f /etc/apcupsd/apcupsd.conf
4497 ?        S      0:00  \_ apcnis        -f /etc/apcupsd/apcupsd.conf

This indicates that apcupsd is up and running and has started the two (default) child processes.

If you are running on a non-Linux system, or using pthreads on a Linux system (recommended), your output will probably not show the names of the processes and will appear more like the following:

632 ?        S      0:00 /sbin/apcupsd -f /etc/apcupsd/apcupsd.conf
841 ?        S      0:00  \_ /sbin/apcupsd -f /etc/apcupsd/apcupsd.conf
842 ?        S      0:00      \_ /sbin/apcupsd -f /etc/apcupsd/apcupsd.conf

If you see only one instance of apcupsd running, don't worry about it unless the communication test fails.

If you do not find that apcupsd is in the above list, the most likely problem is a configuration file glitch. If no messages were printed, you should check your system log (normally /var/log/messages where you will find one or messages indicating the nature of the problem.

Once you have established that the proper processes are running, do a tail of the system log file, normally /etc/var/messages:

tail /etc/var/messages

You should see output that looks similar to the following:

Dec 5 17:01:05 matou apcupsd[5917]: apcupsd 3.7.2
startup succeeded

And if you have configured the network information server, you should also see:

Dec 5 17:01:05 polymatou apcupsd[5975]: apcserver
startup succeeded

These messages should also appear in the temporary file (/etc/apcupsd/apcupsd.events) if you are using the default configuration file.

This test consists of running apcaccess to see if apcupsd is properly updating its internal variables. Please note that if you are running a pthreaded version of apcupsd, which you should be since the non-pthreaded version is no longer supported, (installed from rpm or --enable-pthreads on the ./configure line), you must enable the apcupsd Network Information Server in your configuration file for apcaccess to work. This is done by setting:

NETSERVER on
NISPORT 3551

in your apcupsd.conf file.

To run the apcaccess test, use the following command:

apcaccess status

Depending on the type of UPS you have, you will get slightly different output, but an example For a Smart-UPS is as follows:

APC      : 001,048,1088
DATE     : Fri Dec 03 16:49:24 EST 1999
HOSTNAME : daughter
RELEASE  : 3.7.2
CABLE    : APC Cable 940-0024C
MODEL    : APC Smart-UPS 600
UPSMODE  : Stand Alone
UPSNAME  : SU600   
LINEV    : 122.1 Volts
MAXLINEV : 123.3 Volts
MINLINEV : 122.1 Volts
LINEFREQ : 60.0 Hz
OUTPUTV  : 122.1 Volts
LOADPCT  :  32.7 Percent Load Capacity
BATTV    : 26.6 Volts
BCHARGE  : 095.0 Percent
MBATTCHG : 15 Percent
TIMELEFT :  19.0 Minutes
MINTIMEL : 3 Minutes
SENSE    : Medium
DWAKE    : 000 Seconds
DSHUTD   : 020 Seconds
LOTRANS  : 106.0 Volts
HITRANS  : 129.0 Volts
RETPCT   : 010.0 Percent
STATFLAG : 0x08 Status Flag
STATUS   : ONLINE 
ITEMP    : 34.6 C Internal
ALARMDEL : Low Battery
LASTXFER : Unacceptable Utility Voltage Change
SELFTEST : NO
STESTI   : 336
DLOWBATT : 05 Minutes
DIPSW    : 0x00 Dip Switch
REG1     : N/A
REG2     : N/A
REG3     : 0x00 Register 3
MANDATE  : 03/30/95
SERIALNO : 13035861
BATTDATE : 05/05/98
NOMOUTV  : 115.0
NOMBATTV :  24.0
HUMIDITY : N/A
AMBTEMP  : N/A
EXTBATTS : N/A
BADBATTS : N/A
FIRMWARE : N/A
APCMODEL : 6TD
END APC  : Fri Dec 03 16:49:25 EST 1999

For a simple signaling or dumb UPS such as BackUPS, your output will be very minimal as follows:

APC      : 001,012,0319
DATE     : Mon Feb 18 09:11:50 CST 2002
RELEASE  : 3.8.5
UPSNAME  : UPS_IDEN
CABLE    : APC Cable 940-0128A
MODEL    : BackUPS
UPSMODE  : Stand Alone
STARTTIME: Mon Feb 18 09:11:45 CST 2002
LINEFAIL : OK
BATTSTAT : OK
STATFLAG : 0x008 Status Flag
END APC  : Mon Feb 18 09:15:01 CST 2002

If you see the above output, it is a good sign that apcupsd is working. Assuming that the output looks reasonable, check the following variables:

A very disturbing tendance is for some of the newer (Mar 2004) RS and ES UPSes to have no Voltage information. This is annoying bug not serious. On the other hand, some of those UPSes now have no battery charge information (BCHARGE). If BCHARGE is zero in your listing and you are running a Smart or a USB UPS, then you will have to set the BATTERYLEVEL directive in your apcupsd.conf file to -1.

If you see a message to the effect of:

attach_shmarea: shared memory version mismatch (or UPS not yet ready to report)

or if all the displayed values are zero, you have not waited long enough. Wait a bit longer and then re-execute the apcaccess status command.

If you see a message to the effect of:

APCACCESS FATAL ERROR in apcaccess.c at line 336
tcp_open: cannot connect to server localhost on port 3551.

It means that you have probably not enabled the Network Information Server in your configuration file for apcaccess to work. This is done by setting:

NETSERVER on
NISPORT 3551

in your apcupsd.conf file.

At this point, you should ensure that apcupsd is handling the connection to the UPS correctly. This test assumes you have a UPS that speaks apcsmart protocol, over either USB or a serial port. If you have an old-style voltage-signaling UPS, please skip to the next section (Simulated Power Fail Test).

When apcupsd detects a problem, it generates an EVENT, which consists of sending a message to the system log then invoking the apccontrol script (normally in /etc/acpupsd/apccontrol) to handle the event.

In order to create an event, remove the serial port plug from the back of your computer or from the back of the UPS. Within 6 seconds, apcupsd should detect the lack of serial port communications and broadcast a wall message indicating that the serial port communications was lost:

Warning communications lost with UPS lost.

At the same time, it sends the same message to the system log and to the temporary EVENTS file (/etc/apcupsd/apcupsd.events).

Plug the serial port plug back into your computer, and within about 12 seconds, apcupsd should reestablish communications and broadcast and log the following message:

Communications with UPS restored.

If these messages are logged but not broadcast, either you have your mesg permission set to no (see man wall) or there is a problem with apccontrol. If you are running a window manager such as GNOME and don't have a console window open, you may not receive the wall messages. However, you should find them in your system log file (normally /var/log/messages and in the temporary EVENTS file, /etc/apcupsd/apcupsd.events. For example, to observe these events in the temporary EVENTS file, you might do a

tail -f /etc/apcupsd/apcupsd.events

before running the test.

If you do not observe these messages, you should correct this problem before proceeding with additional tests.

At this point, you should verify that in the event of a power fail apcupsd properly calls apccontrol. This test is appropriate for all models of UPSes (smart or dumb).

To avoid the possibility that apcupsd might shut down your system, locate where apccontrol resides on your system (normally, /etc/apcupsd/apccontrol. Move this script to another location e.g. apccontrol.save and replace it with the script found in examples/safe.apccontrol. When that is done, ensure that your UPS battery is fully charged and that you have at least 5 minutes of remaining runtime on the batteries. This can be done by examining the values of the BATTCHG and TIMELEFT variables in the printout of apcaccess status.

Athough this should not be necessary, as an extra precaution, you can shutdown your machine, remove the plug from the UPS you are testing, and plug your machine into another UPS or directly into the wall. Doing so, will ensure that the UPS doesn't cut the power to your machine at a bad time. Remember at the end of the testing to plug your machine back into the UPS.

You can also minimize the risk from an unexpected shutdown by using a journaling filesystem such as Linux's EXT3. All modern disk drives park themselves safely when they power down, rather than ploughing up oxide on your disk's recording surface. Thus, unexpected power less has to hit very narrow timing windows in order to trash an EXT3 transaction.

To begin the test, pull the power plug from the UPS. The first time that you do this, psychologically it won't be easy, but after you have pulled the plug a few times, you may even come to enjoy it. If all goes well, apcupsd should detect the power failure and print several warning messages. The first should appear after 5 to 6 seconds and read:

Warning power loss detected.

Then generally 6 seconds later, apcupsd is sure that it isn't a transient effect, so it sends:

Power failure. Running on UPS batteries.

After a few more seconds (total around 15 seconds), plug the power cord back in and ensure that apcupsd is aware that the power has returned. It should print:

Power has returned...

If you do not observe the above messages, please correct the situation before proceeding. The most likely cause of problems are:

At this point, we recommend that you do a simulated power down of your system. If you are adventuresome or have been through this before, skip to the next section in this manual and do the real power fail shutdown. If you continue with the simulated power down and if all goes well, apcupsd will go through all the motions without actually shutting down the system. Continue using the safe apccontrol that you installed. Edit the configuration file apcupsd and change the value of TIMEOUT from 0 to something like 30. Doing so will cause apcupsd to attempt to shutdown the system 30 seconds after it detects a power failure. Once this change has been made, you must stop and restart apcupsd for the new configuration value to take effect.

Once again, pull the power plug, and if all goes as expected, apcupsd should attempt to shutdown the system about 30 seconds after it detects the power failure. All the messages should be displayed by wall or by the tail -f command. The precise message is determined by what is printed in /etc/apcupsd/apccontrol for the doshutdown event. Though it varies from system to system, it will generally be something like:

Beginning Shutdown Sequence

When apcupsd this message prints, reconnect the power. apcupsd should detect that the power has been restored and attempt to cancel the shutdown.

IMPORTANT after this test, please replace the changed apccontrol and apcupsd.conf with the original files.

This is an intermediate test that you can do, for all UPS models before doing the Full Power Down Test. First modify the /etc/apcupsd/apccontrol file so that in the killpower) case, the line that re-executes apcupsd with the --killpower option is commented out. The original line probably looks something like:

${APCUPSD} --killpower

when it is commented out, it looks like:

#${APCUPSD}--killpower

Now when you pull the power plug, and either the timer expires or the batteries are exhausted (see the next section for more details), the system should be fully shutdown.

After performing this test, please be sure to restore /etc/apcupsd/apccontrol to its previous state.

To complete the testing, you should do a power fail shutdown of your system. This test is applicable to all UPS models. Please do a backup of your system or take other precautions before attempting this to avoid the possibility of lost data due to a problem (I have been through this at least 10 times and never once had problems, but we all know that someday something will go wrong).

Before proceeding, please ensure that your halt script or the equivalent has been properly updated by the install process to contain the logic to call apcupsd --killpower when it detects a power failure situation (the presence of a /etc/powerfail file). See the Chapter&nspb;&nspb;2, Building and Installing apcupsd of this manual, or the README files for additional details about the halt modifications necessary.

When you are ready to do the test, either simply pull the plug and wait for the batteries to become exhausted, or set the TIMEOUT configuration directive to something like 60 so that the system will shutdown before the batteries are exhausted. We recommend doing the full shutdown without using TIMEOUT to correctly simulate a real power failure, but the choice is yours (I did it once here, but now use TIMEOUT 30).

If all goes well, your system should be shutdown before the batteries are completely exhausted and the UPS should be powered off by apcupsd. Please be aware that if you do the full power down, you must ensure that your UPS is totally powered off. Otherwise, it may have been given the command to power off, but due to a long grace period it is still waiting. If you were to reboot your computer during the grace period, the UPS could then suddenly turn off the power (this happened to me). To avoid this problem, always wait for your UPS to power itself off, or power if off manually before restarting your computer. On my system, the UPS is configured as at the factory to have a 180 second grace period before shutting off the power. During this type of testing, 180 seconds seems like an eternity, so please take care to either wait or manually power off your UPS. To determine what grace period is programmed into your UPS EEPROM, run apcaccess eprom and look at the "Shutdown grace delay".

If you experienced so problems with the above testing procedures, or if you are porting apcupsd to another system, or you are simply curious, you may want to know exactly what is going on during the shutdown process. If so, please see the Shutdown Sequence section of this manual.

apctest is a program that allows you to talk directly to your UPS and run certain low-level tests, display all know values from the UPS's EEPROM, perform a battery runtime calibration, program the EEPROM (serial connection only), and enter in TTY mode with the UPS. Here we describe how to use it for a USB or apcsmart UPS; see the section called “Using apctest on Serial-Line UPSses” for a description of how to use it with a voltage-signalling UPS.

Shutdown apcupsd if it is running. Make sure your /etc/apcupsd/apcupsd.conf file has UPSTYPE smart and UPSCABLE has one of the smart cables that are supported.

Normally apctest will have been built but not installed, so you must execute it from the <bacula-source>/src directory. You can explicitly build it on Unix with:

cd <apcupsd-source-directory>
make apctest
./apctest

or on Windows systems with:

make apctestwin32
./apctest

It will read your installed apcupsd.conf configuration (so it knows where to find the UPS) and then it will present you with the following output:

2003-07-07 11:19:21 apctest 3.10.6 (07 July 2003) redhat
Checking configuration ...
Attached to driver: apcsmart
sharenet.type = DISABLE
cable.type = CUSTOM_SMART

You are using a SMART cable type, so I'm entering SMART test mode
mode.type = SMART
Setting up serial port ...
Creating serial port lock file ...
Hello, this is the apcupsd Cable Test program.
This part of apctest is for testing Smart UPSes.
Please select the function you want to perform.

1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
7) Quit

Select function number: 1

Item 1 will probe the UPS for all values known to apcupsd and present them in rather raw format. This output can be useful for providing technical support if you are having problems with your UPS.

Item 2 will perform a Battery Runtime Calibration. This test will only be performed if your battery is 100% charged. Running the test will cause the batteries to be discharged to approximately 30% of capacity. The exact number depends on the UPS model. In any case, apctest will abort the test if it detects that the battery charge is 20% or less.

The advantage of doing this test is that the UPS will be able to recalibrate the remaining runtime counter that it maintains in its firmware. As your batteries age, they tend to hold less of a charge, so the runtime calibration may not be accurate after several years.

We recommend that perform a Battery Calibration about once a year. You should not perform this calibration too often since discharging the batteries tends to shorten their lifespan.

Item 3 can be used to abort a Battery Calibration in progress, if you some how became disconnected.

Item 4 can be used to restart the monitoring of a Battery Calibration if you should some how become disconnected during the test.

Item 5 is used to program the EEPROM. Please see the the section called “Configuration Directives Used to Set the UPS EPROM” chapter of this manual for the details.

Item 6 will initiate a direct communication between your terminal and the UPS at which point, you can enter raw UPS commands. Please be aware that you should be careful what commands you enter because you can cause your UPS to suddenly shutdown, or you can modify the EEPROM in a way to disable your UPS. The details of the raw Smart mode UPS commands can be found in the UPS Bible chapter of this manual.

Item 7 will terminate apctest.

apcaccess is a program (normally found in /sbin/apcaccess) that permits you to print out the complete status of your UPS. Although there are a number of command line arguments (eprom, reconfig, status, slave, shutdown), all except eprom and status are under development and hence do not work reliably.

If you have built apcupsd with pthreads enabled (default), apcaccess will use the Network Information Server to obtain the necessary information for the status and eeprom commands. This is because in the pthreaded version, there is no IPC shared memory. In this case (pthreads enabled), you can specify a second optional argument to apcaccess in the form of host:port, where the :port is optional. The default is localhost:3551. Please note that in versions prior to 3.10.6, the default NIS port was 7000, so if you are mixing versions, you will need to take a lot of care to ensure that all components are using the same port.

To enable the apcupsd Network Information Server, which is normally the default, you set:

NETSERVER on
NISPORT 3551

in your apcupsd.conf file.

apcaccess status localhost:3551 

APCACCESS FATAL ERROR in apcipc.c at line 325
attach_shmarea: shared memory version mismatch

apcaccess status

DATE     : Fri Dec 03 12:34:26 CET 1999
HOSTNAME : matou
RELEASE  : 3.7.0-beta-1
CABLE    : Custom Cable Smart
MODEL    : SMART-UPS 1000
UPSMODE  : Stand Alone
UPSNAME  : UPS_IDEN
LINEV    : 232.7 Volts
MAXLINEV : 236.6 Volts
MINLINEV : 231.4 Volts
LINEFREQ : 50.0 Hz
OUTPUTV  : 232.7 Volts
LOADPCT  :  11.4 Percent Load Capacity
BATTV    : 27.7 Volts
BCHARGE  : 100.0 Percent
MBATTCHG : 5 Percent
TIMELEFT : 112.0 Minutes
MINTIMEL : 3 Minutes
SENSE    : Low
DWAKE    : 060 Seconds
DSHUTD   : 180 Seconds
LOTRANS  : 204.0 Volts
HITRANS  : 253.0 Volts
RETPCT   : 050.0 Percent
STATFLAG : 0x08 Status Flag
STATUS   : ONLINE 
ITEMP    : 29.2 C Internal
ALARMDEL : Low Battery
LASTXFER : U command or Self Test
SELFTEST : NO
STESTI   : 336
DLOWBATT : 02 Minutes
DIPSW    : 0x00 Dip Switch
REG1     : 0x00 Register 1
REG2     : 0x00 Register 2
REG3     : 0x00 Register 3
MANDATE  : 01/05/99
SERIALNO : GS9902009459
BATTDATE : 01/05/99
NOMOUTV  : 230.0
NOMBATTV :  24.0
HUMIDITY : N/A
AMBTEMP  : N/A
EXTBATTS : 0
BADBATTS : N/A
FIRMWARE : 60.11.I
APCMODEL : IWI
END APC  : Fri Dec 03 12:34:33 CET 1999

Valid EPROM values for the SMART-UPS 1000

                       Config        Current  Permitted
Description              Directive     Value    Values
===================================================================
Upper transfer voltage   HITRANSFER    253      253 264 271 280 
Lower transfer voltage   LOTRANSFER    208      196 188 208 204 
Return threshold         RETURNCHARGE  15       00 15 50 90 
Output voltage on batts  OUTPUTVOLTS   230      230 240 220 225 
Sensitivity              SENSITIVITY   H        H M L L 
Low battery warning      LOWBATT       2        02 05 07 10 
Shutdown grace delay     SLEEP         180      020 180 300 600 
Alarm delay              BEEPSTATE     T        0 T L N 
Wakeup delay             WAKEUP        60       000 060 180 300 
Self test interval       SELFTEST      336      336 168 ON  OFF 

When a major event is generated within apcupsd, control is passed to the script apccontrol normally found in /etc/apcupsd/apccontrol. The event name, and a number of other important parameters are passed to the script.

The major function of the apccontrol script is to performa a shutdown of the system (as well as the killpower operation). In addition, another major task for this script is to notify you by email when certain events such as powerfail occur.

Since apccontrol is a script, you can customize it to your own needs using any text editor. To do so, you must have a minimal knowledge of Unix shell programming. In addition, another feature is that you can write your own scripts that will be automatically called by apccontrol before any of its own code is executed. Details of the events and how to program them are contained in the Advanced topics section entitled Customizing Event Handling.

The UPS has an internal set of timers and remaining capacity counters, which it uses to determine when to shutdown. These are in addition to the apcupsd counters BATTERYLEVEL and MINUTES. As a consequence, apcupsd will shutdown on the first limit that triggers (either an apcupsd limit, or a UPS limit). The UPS internal counter equivalent to BATTERYLEVEL can be found in the hid-ups report as RemainingCapacityLimit, which is typically factory set to 10 percent. In addition, the Low Battery signal is normally given by the UPS when less than 2 minutes of run time remain.

With this release, there are five CGI programs (multimon.cgi, multimoncss.cgi, upsstats.cgi, upsfstats.cgi, and upsimage.cgi). To have them properly installed, you must run the ./configure command with --enable-cgi and you should specify an installation directory with --with-cgi-bin= or load them manually. To install the Cascading Style Sheet, which is used by multimoncss.cgi, you must use the --with-css-dir= option. The default directory for installation of the CGI programs is /etc/apcupsd, which is not really where you want them if you are going to use them. Normally, they should go in the cgi-bin of your Web server.

Once built and loaded, they will give you the status of your UPS or UPSes over the network.

Normally only multimon.cgi or multimoncss.cgiis directly invoked by the user. However, it is possible to directly invoke upsstats.cgi and upsfstats.cgi. upsimage.cgi should never be directly invoked as it is used by upsstats.cgi to produce the bar charts.

If you have a SmartUPS, there are depending on the UPS at least 12 different values stored in the EEPROM that determine how the UPS reacts to various conditions such as high line voltage, low line voltage, power down grace periods, etc.

In general, for the moment, we do not recommend that you change your EEPROM values unless absolutely necessary. There have been several reported cases of problems setting the Low Transfer Voltage. Consequently, if at all possible, do not attempt to change this value.

If despite these warnings, you must change your EEPROM, we recommend connecting your UPS to a Windows or NT machine running PowerChute and making the changes.

apcaccess eeprom

Valid EPROM values for the SMART-UPS 1000

                       Config        Current  Permitted
Description              Directive     Value    Values
================================================================
Upper transfer voltage   HITRANSFER    253      253 264 271 280 
Lower transfer voltage   LOTRANSFER    196      196 188 208 204 
Return threshold         RETURNCHARGE  0        00 15 50 90 
Output voltage on batts  OUTPUTVOLTS   230      230 240 220 225 
Sensitivity              SENSITIVITY   H        H M L L 
Low battery warning      LOWBATT       2        02 05 07 10 
Shutdown grace delay     SLEEP         20       020 180 300 600 
Alarm delay              BEEPSTATE     0        0 T L N 
Wakeup delay             WAKEUP        0        000 060 180 300 
Self test interval       SELFTEST      336      336 168 ON  OFF 

cd <apcupsd-source>/src
su           
<root-password>
./apctest

2003-07-07 11:19:21 apctest 3.10.6 (07 July 2003) redhat
Checking configuration ...
Attached to driver: apcsmart
sharenet.type = DISABLE
cable.type = CUSTOM_SMART

You are using a SMART cable type, so I'm entering SMART test mode
mode.type = SMART
Setting up serial port ...
Creating serial port lock file ...
Hello, this is the apcupsd Cable Test program.
This part of apctest is for testing Smart UPSes.
Please select the function you want to perform.

1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
7) Quit

Select function number: 

This is the EEPROM programming section of apctest.
Please select the function you want to perform.

1) Print EEPROM values
2) Change Battery date
3) Change UPS name
4) Change sensitivity
5) Change alarm delay
6) Change low battery warning delay
7) Change wakeup delay
8) Change shutdown delay
9) Change low transfer voltage
10) Change high transfer voltage
11) Change battery return threshold percent
12) Change output voltage when on batteries
13) Change the self test interval
14) Set EEPROM with conf file values
15) Quit

Select function number: 

Select function number: 1

Doing prep_device() ...

Valid EEPROM values for the SMART-UPS 1000

                       Config        Current  Permitted
Description              Directive     Value    Values
===================================================================
Upper transfer voltage   HITRANSFER    253      253 264 271 280 
Lower transfer voltage   LOTRANSFER    196      196 188 208 204 
Return threshold         RETURNCHARGE  0        00 15 50 90 
Output voltage on batts  OUTPUTVOLTS   230      230 240 220 225 
Sensitivity              SENSITIVITY   H        H M L L 
Low battery warning      LOWBATT       2        02 05 07 10 
Shutdown grace delay     SLEEP         20       020 180 300 600 
Alarm delay              BEEPSTATE     0        0 T L N 
Wakeup delay             WAKEUP        0        000 060 180 300 
Self test interval       SELFTEST      336      336 168 ON  OFF 
===================================================================
Battery date: 07/31/99
UPS Name    : UPS_IDEN

Here is what John Walker has to say about APC UPS batteries:

And Andre Hendrick says:

Finally, here is what Carl Erhorn has to say about batteries:

Here is a link to the APC Battery Store.

apccontrol accepts the following command line options:

To write your own routine for the powerout action, you create shell script named powerout and put it in the lib directory (normally /etc/apcupsd). When the powerout action is invoked by apcupsd, apccontrol will first give control to your script. If you want apccontrol to continue with the default action, simply exit your script with an exit status of zero. If you do not want apccontrol to continue with the default action, your script should exit with the special exit code of 99. However, in this case, please be aware that you must ensure proper shutdown of your machine if necessary.

Some sample scripts (onbattery and mainsback) that email power failure messages can be found in the examples directory of the source code.

If you are setting up a master/slave configuration, you will be required to make some modifications to the apcupsd.conf files after the build is done.

The minimum set of configuration directive changes needed to create a proper master and slave configuration files is described in the Chapter&nspb;&nspb;4, Configuration Examples section of this manual.

The details of these directives are explained in the the section called “Configuration Directives for Sharing a UPS” section of the Configuration chapter of this document.

In addition, sample master and slave configuration files can be found in the <src>/examples directory (apcupsd.master.conf and apcupsd.slave.conf).

When working with a master/slave configuration (one UPS powering more than one computer), the master and slave communicate via the network. In many configurations, apcupsd is started before the network is initialized. In this case, it is possible that the master will be unable to contact the slave. On apcupsd versions prior to 3.8.0, this could cause apcupsd to error off. The solution to this problem is to either force apcupsd to be started after the network and the DNS (fiddle the symbolic links in /etc/rc.d), or put the names of the slave machines in your /etc/hosts file, or even more preferable, use IP addresses rather than machine names. On some configurations, you may need to use fully qualified names (host.domain.xxx) rather than simple host names.

The way to accomplish the above is to ensure that none of the critical files used by each of the two copies of apcupsd are the same. By using suitable configuration options, this is possible.

./configure \
  --prefix=/usr \
  --sbindir=/sbin \
  --with-cgi-bin=/home/http/cgi-bin \
  --enable-cgi \
  --with-css-dir=/home/http/css \
  --with-log-dir=/etc/apcupsd \
  --with-serial-dev=/dev/ttyS0 \
  --enable-pthreads \
  --with-nis-port=3551 \
  --enable-powerflute 

./configure \
  --prefix=$HOME/apcupsd/bin \
  --sbindir=$HOME/apcupsd/bin \
  --enable-cgi \
  --with-cgi-bin=$HOME/apcupsd/bin \
  --with-log-dir=$HOME/apcupsd/bin \
  --with-pid-dir=$HOME/apcupsd/bin \
  --sysconfdir=$HOME/apcupsd/bin \
  --with-lock-dir=$HOME/apcupsd/bin \
  --with-pwrfail-dir=$HOME/apcupsd/bin \
  --with-serial-dev=/dev/ttyS1 \
  --enable-pthreads \
  --with-nis-port=7001 \
  --disable-install-distdir

The Simple Network Management Protocol provides an interface to connect to remote devices through the network. apcupsd is now capable of using the SNMP interface of an SNMP-enabled UPS to communicate with an UPS. Currently apcupsd supports only APC's PowerNet MIB. To enable the SNMP support it is enough to configure the correct device in your apcupsd.conf configuration file. The directive needed for this configuration is:

DEVICE 192.168.100.2:161:APC:private

where the directive is made by four parts:

Follow the instructions in Chapter&nspb;&nspb;2, Building and Installing apcupsdl, being sure to include the following options (in addition to any others you need) on the ./configure line:

./configure \
--with-serial-dev=<your-SNMP-device> \
--with-upstype=snmp \
--with-upscable=smart \
--enable-pthreads \
--enable-snmp

The SNMP connection gives less information compared to a serial smart cable. This is not a problem as the most useful information is given, together with a number of secondary parameters that are informative enough to run safely your UPS.

Currently (as of 3.10.0) the code to power off the UPS needs special configuration. The killpower command for SNMP UPSes can not be issued during shutdown as typically at some time during shutdown operations the network stack is stopped. To overcome this problem it is needed to modify the /etc/rc.d/apcupsd system control script to tell apcupsd to issue the power down command (killpower) to the UPS immediately before apcupsd initiates the system shutdown. For this reason it is paramount to set your UPS grace time to a value greater than 120 seconds to allow for clean shutdown operations before the UPS removes the power from its plugs. To enable correct shutdown operation during powerdown do the following:

With this setup your UPS operations should be safe.

This is probably the simplest way to run the network information server. To do so, you simply make sure the NETSERVER directive in /etc/apcupsd/apcupsd.conf is on, and then stop and restart apcupsd. It will automatically create the server thread (or spawn an additional child process named apcnis) to handle network clients. In the case where pthreads are enabled, a new thread will be created rather than a child process to handle the network information requests. Note, the above modification should not be necessary if you use the default apcupsd.conf, since it is already turned on.

Although this method is simple, it affords no protection from the outside world accessing your network server unless you are behind a firewall. In addition, if there is a bug in the network server code, or if a malicious user sends bad data, it may be possible for apcnis to die, in which case, though it is not supposed to, apcupsd may also exit, thus leaving your machine without shutdown protection. In addition, since apcupsd is running at root level, all threads or any child process will do so also. That being said, most of us prefer to run the server this way.

With apcupsd version 3.8.2 and later, you may enable the TCP Libwrap subroutines to add additional security. In this case, access to the network server will be controlled by the statements you put in /etc/hosts.allow.

This is probably the most secure and most desirable way of running the network information server. Unfortunately, it is a bit more complicated to set up. However, once running, the server remains unexecuted until a connection is attempted, at which point, inetd will invoke apcnisd. Once apcnisd has responded to the client's requests, it will exit. None of the disadvantages of running it standalone apply since apcnisd runs only when a client is requesting data. Note, running in this manner works only if you are using the old forking code and have pthreads explicitly turned off. The pthreads version of apcupsd does not support the shared memory calls that are necessary for apcnisd to access the internal state of apcupsd.

An additional advantage of this method of running the network information server is that you can call it with a TCP wrapper and thus use access control lists (ACL) such as hosts.allow. See the man pages for hosts.allow for more details.

To configure apcnisd to run from INETD, you must first put an entry in /etc/services as follows:

apcnisd         3551/tcp

This defines the port number (3551) and the service (TCP) that apcnisd will be using. This statement can go anywhere in the services file. Normally, one adds local changes such as these to the end of the file.

Next, you must modify /etc/inetd.conf to have the following line:

apcnisd stream  tcp     nowait  root    /usr/sbin/tcpd  /sbin/apcnisd -i

If you do not want to run the TCP wrapper, then the line should be entered as follows (not tested):

apcnisd stream  tcp     nowait  root    /sbin/apcnisd -i

Please check that the file locations are correct for your system. Also, note that the -i option is necessary so that apcnisd knows that it was called by INETD. Before restarting INETD, first ensure that the NETSERVER directive in /etc/apcupsd/apcupsd.conf is set to off. This is necessary to prevent apcupsd from starting a child process that acts as a server. If you change NETSERVER, you must stop and restart apcupsd for the configuration change to be effective.

Finally, you must restart INETD for it to listen on port 3551. On a Red Hat system, you can do so by:

/etc/rc.d/init.d/inet reload

At this point, when a client attempts to make a connection on port 3551, INETD will automatically invoke apcnisd.

This is probably the least desirable of the three ways to run an apcupsd network information server because if apcupsd is stopped, you must also stop apcnisd before you can restart apcupsd. This is because apcnisd, when run standalone, holds the shared memory buffer by which apcnisd and apcupsd communicate. This prevents a new execution of apcupsd from creating it.

To execute apcnisd in standalone mode, first ensure that the NETSERVER directive in /etc/apcupsd/apcupsd.conf is set to off. This is necessary to prevent apcupsd from starting a child process that acts as a server. Restart apcupsd normally, then:

/sbin/apcnisd

The advantage of running the network information server standalone is that if for some reason, a client causes the network server to crash, it will not affect the operation of apcupsd.

apcupsd splits its logging into four separate types called:

Debug logging consists of debug messages. Normally these are turned on only by developers, and currently there exist very few of these debug messages.

DATA Logging

Data logging consists of periodically logging important data concerning the operation of the UPS. See the Data Logging section of this manual for more details.

STATUS Logging

Status logging consists of logging all available information known about your UPS as a series of ASCII records. This information is also made available by the apcupsd network information server.

For more details on STATUS logging, see the Status section of the Technical Reference.

EVENTS Logging

Events logging consists of logging events as they happen. For example, successful startup, power fail, battery failure, system shutdown, ...

See the manual section on customizing event handling for more details.

In order to ensure that the data logged to syslog() can be directed to different files, I have assigned syslog() levels to each of our four types of data as follows:

It should be noted that more work needs to be done on the precise definitions of each of the levels for EVENTS logging. Currently, it is roughly broken down as follows:

LOG_WARNING general information such as startup, etc.

LOG_ERR an error condition detected, e.g. communications problem with the UPS.

LOG_CRIT a serious problem has occurred such as power failure, running on UPS batteries, ...

LOG_ALERT a condition that needs immediate attention such as pending system shutdown, ...

The default Facility for syslog() logging is DAEMON, although this can be changed with the FACILITY directive in apcupsd.conf. In the following example, we should the facility as local0.

More work needs to be done to the code to ensure that it corresponds to the above levels.

As a practical example of how to setup your syslog() to use the new logging feature, suppose you wish to direct all DATA logging to a file named /var/log/apcupsd.data, all EVENTS to the standard /var/log/messages file (to be mixed with other system messages), and at the same time send all EVENTS to /var/log/apcupsd.events, and finally, you want to send all STATUS logging to the named pipe /var/log/apcupsd.status

First as root, you create the named pipe:

mkfifo /var/log/apcupsd.status

Change its permissions as necessary or use the -m option to set them when creating the pipe.

Then you modify your /etc/syslog.conf file to direct the appropriate levels of messages where you want them. To accomplish the above, my syslog.conf file looks like:

# exclude all apcupsd info by default
*.info;local0.none                    /var/log/messages

# Everything for apcupsd goes here
local0.info;local0.!notice             /var/log/apcupsd.data
local0.notice;local0.!warn            |/var/log/apcupsd.status
local0.warn                            /var/log/apcupsd.events
local0.warn                            /var/log/messages

All logging functions and all error reporting are now done through the log_event() subroutine call. Exceptions to this are: initialization code where printf's are done, and writing to the status file. Once the initialization code has completed and the fork() to become a daemon is done, no printf's are used. log_event() has exactly the same format as syslog(). In fact, the subroutine consists of only a syslog() call. If anyone really wishes to log to a file, the code to do so can easily be done by adding code to log_event() in apclog.c.

Normally, you will install the Windows version of apcupsd from the binaries. This install is somewhat Unix like since you do many parts of the installation by hand. To install the binaries, you need WinZip.

If you wish to install the package elsewhere, please note that you will need to proceed with a manual installation, which is not particularly easy as you must rebuild the source and change the configuration file as well.

This installation assumes that you do not have CYGWIN installed on your computer. If you do, and you use mount points, you may need to do a special manual installation.

Once you have unzipped the binaries, open a window pointing to the binary installation folder (normally c:\apcupsd). This folder should contain folders with the name bin, etc, examples, and manual. If and when you no longer need them, the examples and manual sub-folders of the c:\apcupsd directory may be removed.

Continuing the installation process:

You probably should also click on the Startup... button to ensure that the correct defaults are set. The dialogue box that appears should have Startup Type set to Automatic and Logon should be set to System Account with Allow Service to Interact with Desktop checked. If these values are not set correctly by default, please change them otherwise apcupsd will not work.

For WinXP systems (and probably Win2K), the dialogs are a bit different from those shown here for WinNT, but he concept is the same. You get to the Services dialog by clicking on: Control Panel -> Administrative Tools -> Component Services. The apcupsd service should appear in the right hand window when you click on Services (Local) in the left hand menu window.

That should complete the installation process. When the system tray icon turns from a battery into a plug , right click on it and a menu will appear. Select the Events item, and the Events dialogue box should appear. There should be no error messages. By right clicking again on the system tray plug and selecting the Status item, you can verify that all the values for your UPS are correct.

When the UPS switches to the battery, the battery icon will reappear in the system tray. While the UPS is online, if the battery is not at least 99% charged, the plug icon will become a plug with a lightning bolt in the middle to indicate that the battery is charging.

The Win32 version of apcupsd must reside in the c:\apcupsd\ directory, and there must be a c:\tmp directory on your machine. The installation will do this automatically, and we recommend that you do not attempt to place apcupsd in another directory. If you do so, you are on your own, and you will need to do a rebuild of the source.

It would be hard to overemphasize the need to do a full testing of your installation of apcupsd as there are a number of reasons why it may not behave properly in a real power failure situation.

Please read Chapter&nspb;&nspb;5, Testing Apcupsd of this document for general instructions on testing the Win32 version. However, on Win32 systems, there is no Unix system log file, so if something goes wrong, look in the file c:\apcupsd\etc\apcupsd\apcupsd.events where apcupsd normally logs its events, and you will generally find more detailed information on why the program is not working. The most common cause of problems is either improper configuration of the cable type, or an incorrect address for the serial port.

On Win98 and Win95 systems, to upgrade to a new release, simply stop apcupsd by using the tray icon and selecting the Close apcupsd menu item, or by double clicking on the Stop icon located in the c:\apcupsd\bin directory, then apply the upgrade and restart apcupsd.

On WinNT systems (and Win2000 systems), you may stop apcupsd as indicated abover or alternatively you may stop apcupsd by using the Services item in the Control Panel. In addition, at least on my system, there seems to be a WinNT bug that causes the system to prevent apcupsd.exe from being overwritten even though the file is no longer being used. This is manifested by an error message when attempting load a new version and overwrite the old apcupsd.exe (the extract part of WinZip as described above). To circumvent this problem (if it happens to you), after shutting down the running version of apcupsd, through the Services dialogue in the Control Panel, first click on the Stop button:

then click on the Startup ... button, and in the Startup dialogue select the Disabled button to disable apcupsd:

After closing the dialogues, reboot the system, typical of Microsoft :-(. When the system comes back up, apcupsd will not be automatically launched as a service, and you can install the new version. To reinstate apcupsd as an automatic service, using the Control Panel: reset apcupsd to Automatic startup in the Startup dialogue, then restart apcupsd in the Services dialogue as shown above in the installation instructions. Frequently after an upgrade, you will click on the Start button and after a few seconds, the system reports that it failed to start. The cause of this problem is unknown, but the solution is simply to click again on the Start button.

After installing apcupsd and before running it, you should check the contents of two files to ensure that it is configured properly for your system. The first is c:\apcupsd\etc\apcupsd\apcupsd.conf. You will probably need to change your UPSCABLE directive, your UPSTYPE and possibly your DEVICE directives. Please refer to the configuration section of this manual for more details.

The second file that you should examine is c:\apcupsd\etc\apcupsd\apccontrol. This file is called by apcupsd when events (power loss, etc) are generated. It permits the user to program handling the event. In particular, it permits the user to be notified of the events. For the Win32 version, each event is programmed to display a Windows popup dialogue box. If your machine is mostly unattended, you may want to comment out some of these popup dialogue boxes by putting a pound sign (#) in column one of the appropriate line.

In addition to possible problems of reinstallation or upgrade on WinNT systems, as noted above, we have discovered the following problem: On some Windows systems, the domain resolution does not seem to work if you have not configured a DNS server in the Network section of the Control Panel. This problem should be apparent only when running a master or a slave configuration. In this case, when you specify the name of the master or the slave machine(s) in your apcupsd.conf file, apcupsd will be unable to resolve the name to a valid IP address. To circumvent this problem, simply enter all machine addresses as an IP address rather than a domain name, or alternatively, ensure that you have a valid DNS server configured on your system (often not the case on Win32 systems). For example, instead of using the directive "MASTER my.master.com" use something like "MASTER 192.168.1.54" where you replace the IP address with your actual IP address.

Also, on WinNT systems, the PIF files in /apcupsd/bin used for starting and stopping apcupsd do not work. Use the services control panel instead.

On Win95 systems, there are reports that the PIF files do not work. If you find that to be the case, the simplest solution is to use the batch files that we have supplied in the c:/apcupsd/bin directory. Also, on Win95 systems, we have an unconfirmed report that indicates that apcupsd does not start automatically as a service even though the Registry has been properly updated. If you experience this problem, a work around is to put a shortcut to apcupsd in the StartUp folder.

As noted above, after an upgrade, you may need to start apcupsd several times before it will actually run.

On WinNT, WinXP, and Win2K systems, you can examine the System Applications log to which apcupsd writes Windows error messages during startup.

Regardless of which Windows system you are running, apcupsd logs most error messages to c:\apcupsd\etc\apcupsd\apcupsd.events. This type error messages such as configuration file not found, etc are written to this file.

The directory c:\apcupsd\bin contains six utility routines (actually .pif files) that you may find useful. They are:

Start
Stop
Install
Uninstall
ups-events
ups-status

Any of these utilities may be used on any system, with the exception of the Start utility, which cannot be used on WinNT and Win2000 systems. On those systems, the apcupsd service must always be started through the Services sub-dialogue of the Control Panel.

The Install and Uninstall utilities install and uninstall apcupsd from the system registry only. All other pieces (files) of apcupsd remain intact. It is not absolutely necessary for apcupsd to be installed in the registry as it can run as a regular program. However, if it is not installed in the registry, it cannot be run as a service.

The functions of Stop, ups-events, and ups-status can be more easily invoked by right clicking on the apcupsd icon in the system tray and selecting the desired function from the popup menu.

Some of the features such as EEPROM programming have not been exhaustively tested on Win32 systems. If at all possible, we recommend not to use it as a network master on Win95, Win98, and WinMe due to the instability of those operating systems.

Some items to note:

On Win95/98 systems, it is possible to receive notification of apcupsd events that are passed to apccontrol. This is possible using a simple email program that unfortunately is not functioning 100% correctly. In addition, I (Kern) was not able to make this program work on WinNT while apcupsd is running as a service under the system account (it works fine with any user account).

If you wish to try this program on Win95/98 systems, look at the files named changeme, commfailure, commok, onbattery, and mainsback in the directory c:\apcupsd\examples. To use them, you must modify the SYSADMIN variable to have a valid email address, then copy the files into the directory c:\apcupsd\etc\apcupsd.

If your batteries become exhausted during a power failure and you want your machine to automatically reboot when the power comes back, it is useful to implement the killpower feature of the UPS where apcupsd sends the UPS the command to shut off the power. In doing so, the power will be cut to your PC and if your BIOS is properly setup, the machine will automatically reboot when the power comes back. This is important for servers.

This feature is implemented on Unix systems by first requesting a system shutdown. As a part of the shutdown, apcupsd is terminated by the system, but the shutdown process executes a script where apcupsd is recalled after the disks are synced and the machine is idle. Bacula then requests the UPS to shut off the power (killpower).

Unfortunately on Windows, there is no such shutdown script that we are aware of and no way for apcupsd to get control after the machine is idled. If this feature is important to you, it is possible to do it by telling apcupsd to immediately issue the killpower command after issuing the shutdown request. The danger in doing so is that if the machine is not sufficiently idled when the killpower takes place, the disks will need to be rescanned (and there is a possibility of lost data however small). Generally, UPSes have a shutdown grace period which gives sufficient time for the OS to shutdown before the power is cut.

To implement this feature, you need to add the -p option to the apcupsd command line that is executed by the system. Currently the procedure is manual. You do so by editing the registry and changing the line:

c:\apcupsd\apcupsd.exe /service

found under the key:

HKEY_LOCAL_MACHINE Software\Microsoft\Windows\CurrentVersion\RunServices

to

c:\apcupsd\apcupsd.exe /service -p

If you have a Smart UPS, you can configure the kill power grace period, and you might want to set it to 3 minutes. If you have a dumb UPS, there is no grace period and you should not use this procedure. If you have a Back-UPS CS or ES, these UPSes generally have a fixed grace period of 2 minutes, which is probably sufficient.

Our philosophy is to shutdown a computer but not to power it down itself (as opposed to having the UPS cut the power as described above). That is we prefer to idle a computer but leave it running. This has the advantage that in a power fail situation, if the killpower function described above does not work, the computer will continue to draw down the batteries and the UPS will hopefully shutoff before the power is restore thus permitting an automatic reboot.

Nevertheless some people prefer to do a full power down. To do so, you might want to get a copy of PsShutdown, which does have a power down option. You can find it and a lot more useful software at: http://www.sysinternals.com/ntw2k/freeware/pstools.shtml. to use their shutdown program rather than the apcupsd supplied version, you simply edit:

c:\apcupsd\etc\apcupsd\apccontrol

with any text editor and change our calls to shutdown to psshutdown.

These options are not normally seen or used by the user, and are documented here only for information purposes. At the current time, to change the default options, you must either manually run apcupsd or you must manually edit the system registry and modify the appropriate entries.

In order to avoid option clashes between the options necessary for apcupsd to run on Windows and the standard apcupsd options, all Windows specific options are signaled with a forward slash character (/), while as usual, the standard apcupsd options are signaled with a minus (-), or a minus minus (--). All the standard apcupsd options can be used on the Windows version. In addition, the following Windows only options are implemented:

It is important to note that under normal circumstances the user should never need to use these options as they are normally handled by the system automatically once apcupsd is installed. However, you may note these options in some of the .pif files that have been created for your use.

If you have the source code, follow the standard procedures for building apcupsd on Unix in Chapter&nspb;&nspb;2, Building and Installing apcupsd of this manual. Please don't forget to look at the system specifics for CYGWIN.

  SMART-CUSTOM CABLE

Signal Computer                  UPS
       DB9F                     DB9M
 RxD    2   --------------------  2  TxD  Send
 TxD    3   --------------------  1  RxD  Receive
 GND    5   --------------------  9  Ground

When using this cable with apcupsd specify the following in apcupsd.conf:

If you have an OS that requires DCD or RTS to be set before you can receive input, you might try building the standard APC Smart 940-0024C cable listed below.

UPSCABLE smart
UPSTYPE apcsmart
DEVICE /dev/ttyS0 (or whatever your serial port is)

If you wish to build the standard cable furnished by APC (940-0024C), use the following diagram.

  APC Smart Cable 940-0024C

Signal Computer                  UPS
       DB9F                     DB9M
 RxD    2   --------------------  2  TxD  Send
 TxD    3   --------------------  1  RxD  Receive
 DCD    1   --*
              |
 DTR    4   --*
 GND    5   --------------------  9  Ground
 RTS    7   --*
              |
 CTS    8   --*

If you have a BackUPS CS, you are probably either using it with the USB cable that is supplied or with the 940-0128A supplied by APC, which permits running the UPS in dumb mode. By building your own cable, you can now run the BackUPS CS models (and perhaps also the ES models) using smart signalling and have all the same information that is available as running it in USB mode.

The jack in the UPS is actually a 10 pin RJ45. However, you can just as easily use a 8 pin RJ45 connector, which is more standard (ethernet TX, and ISDN connector). It is easy to construct the cable by cutting off one end of a standard RJ45-8 ethernet cable and wiring the other end (three wires) into a standard DB9F female serial port connector.

Below, you will find a diagram for the CUSTOM-RJ45 cable:

  CUSTOM-RJ45 CABLE

Signal Computer              UPS     UPS
       DB9F                 RJ45-8  RJ45-10
 RxD    2   ----------------  1      2     TxD  Send
 TxD    3   ----------------  7      8     RxD  Receive
 GND    5   ----------------  6      7     Ground

The RJ45-8 pins are: looking at the end of the connector:

 8 7 6 5 4 3 2 1
___________________
| . . . . . . . . |
|                 |
-------------------
       |____|

The RJ45-10  pins are: looking at the end of the connector:

10 9 8 7 6 5 4 3 2 1
_______________________
| . . . . . . . . . . |
|                     |
-----------------------
       |____|

For the serial port DB9F connector, the pin numbers are stamped in the plastic near each pin. In addition, there is a diagram near the end of this chapter.

When using this cable with apcupsd specify the following in apcupsd.conf:

UPSCABLE smart
UPSTYPE apcsmart
DEVICE /dev/ttyS0 (or whatever your serial port is)

The information for constructing this cable was discovered and transmitted to us by slither_man. Many thanks!

NOTE. YOU DO NOT HAVE THIS CABLE UNLESS YOU BUILT IT YOURSELF. THE SIMPLE-CUSTOM CABLE IS NOT AN APC PRODUCT.

For "dumb" UPSes using voltage signalling, if you are going to build your own cable, we recommend to make the cable designed by the apcupsd team as follows:

       SIMPLE-CUSTOM CABLE

Signal Computer                  UPS
       DB9F   4.7K ohm          DB9M
 DTR    4   --[####]--*              DTR set to +5V by Apcupsd
                      |
 CTS    8   ----------*---------  5  Low Battery
 GND    5   --------------------  4  Ground
 DCD    1   --------------------  2  On Battery
 RTS    7   --------------------  1  Kill UPS Power

List of components one needs to make the Simple cable:

We use the DTR (pin 4 on the female connector) as our +5 volts power for the circuit. It is used as the Vcc pull-up voltage for testing the outputs on any "UPS by APC" in voltage-signalling mode. This cable may not work on a BackUPS Pro if the default communications are in apcsmart mode. This cable is also valid for "ShareUPS" BASIC Port mode and is also reported to work on SmartUPSes. However, the Smart Cable described above is much simpler. To have a better idea of what is going on inside apcupsd, for the SIMPLE cable apcupsd reads three signals and sets three:

Reads:
CD, which apcupsd uses for the On Battery signal when high.

CTS, which apcupsd uses for the Battery Low signal when high.

RxD (SR), which apcupsd uses for the Line Down 
    signal when high. This signal isn't used for much.

Sets:
DTR, which apcupsd sets when it detects a power failure (generally
     5 to 10 seconds after the CD signal goes high). It
     clears this signal if the CD signal subsequently goes low
     -- i.e. power is restored.

TxD (ST), which apcupsd clears when it detects that the CD signal
     has gone low after having gone high - i.e. power is restored.

RTS, which apcupsd sets for the killpower signal -- to cause the UPS
     to shut off the power.

Please note that these actions apply only to the SIMPLE cable, the signals used on the other cables are different.

Finally, here is another way of looking at the CUSTOM-SIMPLE cable:

APCUPSD SIMPLE-CUSTOM CABLE

Computer Side  |  Description of Cable           |     UPS Side  
DB9f  |  DB25f |                                 |   DB9m  | DB25m
4     |   20   |  DTR (5vcc)             *below  |    n/c  |
8     |    5   |  CTS (low battery)      *below  | <-  5   |   7
2     |    3   |  RxD (no line voltage)  *below  | <-  3   |   2
5     |    7   |  Ground (Signal)                |     4   |  20
1     |    8   |  CD (on battery from UPS)       | <-  2   |   3
7     |    4   |  RTS (kill UPS power)           | ->  1   |   8
n/c   |    1   |  Frame/Case Gnd (optional)      |     9   |  22

Note: the <- and -> indicate the signal direction.

Optional connections of original SIMPLE-CUSTOM specification
that are not used.

              4.7K ohm
 DTR    4   --[####]--*              Note needed
                      |
 RxD    2   ----------*---------  3  Not used by Apcupsd

When using this cable with apcupsd specify the following in apcupsd.conf:

UPSCABLE simple
UPSTYPE dumb
DEVICE /dev/ttyS0 (or whatever your serial port is)

apcupsd will also support the following off the shelf cables that are supplied by APC

The following table shows the features supported by the current version of apcupsd (3.8.5 or later) for various cables running the UPS in voltage-signalling mode.

Apparently, all APC voltage-signalling UPSes have the same signals on the output pins of the UPS. The difference at the computer end is due to different cable configurations. Thus, by measuring the connectivity of a cable, one can determine how to program the UPS. This is to be verified.

The signals presented or accepted by the UPS on its DB9 connector using the numbering scheme listed above is:

UPS Pin         Signal meaning
 1     <-     Shutdown when set by computer for 1-5 seconds.
 2     ->     On battery power (this signal is normally low but
                    goes high when the UPS switches to batteries).
 3     ->     Mains down (line fail) See Note 1 below.
 5     ->     Low battery. See Note 1 below.
 6     ->     Inverse of mains down signal. See Note 2 below.
 7     <-     Turn on/off power (only on advanced UPSes only)

 Note 1: these two lines are normally open, but close when the
     appropriate signal is triggered. In fact, they are open collector
     outputs which are rated for a maximum of +40VDC and 25 mA. Thus
     the 4.7K ohm resistor used in the Custom Simple cable works 
     quite well.

 Note 2: the same as note 1 except that the line is normally closed,
     and opens when the line voltage fails.

The Back-UPS Office UPS has a telephone type jack as output, which looks like the following:

Looking at the end of the connector:

   6 5 4 3 2 1
  _____________
 | . . . . . . |
 |             |
 |  |----------|
 |__|

It appears that the signals work as follows:

  UPS            Signal meaning
1 (brown)    <-   Shutdown when set by computer for 1-5 seconds.
2 (black)    ->   On battery power
3 (blue)     ->   Low battery
4 (red)           Signal ground 
5 (yellow)   <-   Begin signalling on other pins
6 (none)          none

Due to inadequacies in the Win32 API, it is not possible to set/clear/get all the serial port line signals. apcupsd can detect: CTS, DSR, RNG, and CD. It can set and clear: RTS and DTR.

This imposes a few minor restrictions on the functionality of some of the cables. In particular, LineDown on the Custom Simple cable, and Low Battery on the 0023A cable are not implemented.

This section describes how apcupsd 3.8.5 (March 2002)
treats the serial port line signals for simple cables.

apcaction.c: 
 condition = power failure detected
 cable = CUSTOM_SIMPLE
 action = ioctl(TIOCMBIS, DTR)      set DTR (enable power bit?)

apcaction.c: 
 condition = power back
 cable = CUSTOM_SIMPLE
 action = ioctl(TIOCMBIC, DTR)      clear DTR (clear power bit)
 action = ioctl(TIOCMBIC, ST)       clear ST (TxD)

apcserial.c: 
 condition = serial port initialization
 cable = 0095A, 0095B, 0095C
 action = ioctl(TIOMBIC, RTS)       clear RTS (set PnP mode)

 cable = 0119A, 0127A, 0128A
 action = ioctl(TIOMBIC, DTR)       clear DTR (killpower)
 action = ioctl(TIOMBIS, RTS)       set   RTS (ready to receive)

apcserial.c: 
 condition = save_dumb_status
 cable = CUSTOM_SIMPLE
 action = ioctl(TIOMBIC, DTR)       clear DTR (power bit?)
 action = ioctl(TIOMBIC, RTS)       clear RTS (killpower)

 cable = 0020B, 0020C, 0119A, 0127A, 0128A
 action = ioctl(TIOMBIC, DTR)       clear DTR (killpower)

 cable = 0095A, 0095B, 0095C
 action = ioctl(TIOMBIC, RTS)       clear RTS (killpower)
 action = ioctl(TIOMBIC, CD)        clear DCD (low batt)
 action = ioctl(TIOMBIC, RTS)       clear RTS (killpower) a second time!

apcserial.c:
 condition = check_serial

 cable = CUSTOM_SIMPLE
 action = OnBatt = CD
 action = BattLow = CTS
 action = LineDown = SR

 cable = 0020B, 0020C, 0119A, 0127A, 0128A
 action = OnBatt = CTS
 action = BattLow = CD
 action = LineDown = 0

 cable = 0023A
 action = Onbatt = CD
 action = BattLow = SR
 action = LineDown = 0

 cable = 0095A, 0095B, 0095C
 action = OnBatt = RNG
 action = BattLow = CD
 action = LineDown = 0


apcserial.c
 condition = killpower

 cable = CUSTOM_SIMPLE, 0095A, 0095B, 0095C
 action = ioctl(TIOMCBIS, RTS)      set RTS (kills power)
 action = ioctl(TIOMCBIS, ST)       set TxD       

 cable = 0020B, 020C, 0119A, 0127A, 0128A
 action = ioctl(TIOMCBIS, DTR)      set DTR (kills power)

   13                         1         5         1
 _______________________________      _______________
 \  . . . . . . . . . . . . .  /      \  . . . . .  /    RS232-connectors
  \  . . . . . . . . . . . .  /        \  . . . .  /     looking into the
   ---------------------------          -----------      end of the cable.
   25                      14            9       6

The diagram above represents the Female end of the cable. The
male end is the same, but looking from inside the cable.

 DTE : Data Terminal Equipment (i.e. computer)
 DCE : Data Communications Equipment (i.e. UPS)
 RxD : Data received; 1 is transmitted "low", 0 as "high"
 TxD : Data sent; 1 is transmitted "low", 0 as "high"
 DTR : DTE announces that it is powered up and ready to communicate
 DSR : DCE announces that it is ready to communicate; low=modem hang-up
 RTS : DTE asks DCE for permission to send data
 CTS : DCE agrees on RTS
 RI  : DCE signals the DTE that an establishment of a connection is attempted
 DCD : DCE announces that a connection is established

#define TIOCM_LE        0x001
#define TIOCM_DTR       0x002
#define TIOCM_RTS       0x004
#define TIOCM_ST        0x008
#define TIOCM_SR        0x010
#define TIOCM_CTS       0x020
#define TIOCM_CAR       0x040
#define TIOCM_RNG       0x080
#define TIOCM_DSR       0x100
#define TIOCM_CD        TIOCM_CAR
#define TIOCM_RI        TIOCM_RNG
#define TIOCM_OUT1      0x2000
#define TIOCM_OUT2      0x4000

Once you have compiled, installed, and invoked apcupsd, you should wait to allow apcupsd to configure itself and establish contact with the UPS.

If you see the following message about 30 seconds after starting apcupsd:

apcupsd FATAL ERROR in apcserial.c at line 156
PANIC! Cannot communicate with UPS via serial port.

it means that apcupsd tried for about 30 seconds to establish contact with the UPS via the serial port, but was unable to do so. Before continuing, you must correct this problem. Some of the possible sources of the problem are:

The first thing to do is to look at your log file, usually /var/log/messages because apcupsd writes more detailed information to the log file whenever there is an error.

If you have a UPS that uses apcsmart protcol (see table of types for a list of the UPSes using these protocols), you can manually test the serial communications with the UPS by starting a serial port communications program (such as minicom, tip, or cu) with the settings 2400 8N1 (2400 baud, 8 bits, no parity, 1 stop bit). Be extremely careful what you send to your UPS as certain characters may cause it to power down or may even cause damage to the UPS. Try sending an upper case Y to the UPS (without a return at the end). It should respond with SM. If this is not the case, review the possible problems listed above. If you fat finger the Y and enter y instead, no cause for alarm, you will simply get the APC copyright notice.

Once you are sure that serial port communications is working, proceed to the next test.

On an apcsmart serial-line UPS, apctest will give you access to the battery of low-level tests we described in the section called “apctest”. If you have a voltage-signalling UPS, it enables a different test repertoire which is described here, Among other things, if you are uncertain about what kind of cable you have, you may be able to use apctest to figure that out.

Shutdown apcupsd if it is running. Make sure your /etc/apcupsd/apcupsd.conf file has UPSTYPE backups and UPSCABLE simple Normally apctest will have been built and installed by default, otherwise, you can explicitly build it on Unix with:

cd <apcupsd-source-directory>
make apctest
./apctest

on Win32 systems, use:

make apctestwin32
./apctest

It will present you with the following output

2001-02-07 04:08:26 apctest 3.8.5 (3 January 2002) redhat
Checking configuration ...
sharenet.type = DISABLE
cable.type = CUSTOM_SIMPLE
mode.type = BK
Setting up serial port ...
Creating serial port lock file ...
Doing prep_serial() ...
Hello, this is the apcupsd Cable Test program.
This part of apctest is for testing dumb UPSes (ones that uses signaling rather than commands.
Most tests enter a loop polling every second for 10 seconds.

Then it will present you with the following list of choices:

1) Test 1 - normal mode
2) Test 2 - no cable
3) Test 3 - no power
4) Test 4 - low battery (requires test 3 first)
5) Test 5 - battery exhausted
6) Test 6 - kill UPS power
7) Test 7 - run tests 1 through 5
8) Guess which is the appropriate cable
9) quit

Select test number: 

Run tests 1, 2, and 3. Note, none of the currently supported cables will indicate a change for test 2. You can then run test 8 to see what cable it thinks you should be using. Finally run test 4.

apctest can also be run for Smart UPSes.

The print out of your testing will be written to the file apctest.output. If you are unable to solve your problem, you can try posting that file to the development mailing list, and perhaps we can help you. In this case, please also include information on your operating system, which version of apcupsd you are using, your UPS model, and also your apcupsd.conf file.

UPSTYPE backups
UPSCABLE APC_940_0119A
    or APC_940_0127A
    or APC_940_0128A
    or APC_940_0020B
    or APC_940_0020C

Test 1 normal:              RTS for cables (0119A 0127A 0128A)
Test 2 no serial cable:     not important
Test 3 no AC power:         CTS for all cables
Test 4 batteries exhausted: CTS and CD for all cables

UPSTYPE backupspro
UPSCABLE APC_940_0095A
    or APC_940_0095C

Test 1 normal:              RTS not set
Test 2 no serial cable:     not important
Test 3 no AC power:         RNG
Test 4 batteries exhausted: RNG and CD

The most frequently encountered problem with voltage-signalling UPSes (e.g. BackUPS 650) is that you have incorrectly specified which cable is being used. All cables furnished by APC have the cable number stamped on the side of the computer connector end of the cable. Using this number with apcupsd will normally work fine. If you do not know what cable you have, you can use the apctest program to determine the type of the cable.

For simple signaling UPSes, you should not use simple in the cable specification (i.e. UPSCABLE simple) unless you have made the cable yourself according to the wiring diagram given in the cables chapter of this manual.

Once you have established that apcupsd can talk to the UPS over the serial part, go do the series of functional tests described in the main Testing section.

One additional note applies:

Serial-line UPSes that speak the apcsmart protocol log all of the events described in the Status Format section of the Technical Reference. Voltage-signalling UPSes, on the other hand, have a much narrower data channel. They can only report a small handful of conditions.

The following summarizes (rather sketchily, sorry) the data you can expect to get from this obsolete hardware. All corrections and additions will be welcome.

From BackUPS Pro and SmartUPS v/s:

LINEFAIL : OnlineStatus
BATTSTAT : BatteryStatus
MAINS    : LineVoltageState
LASTEVNT : LastEventObserved

BackUPS and NetUPS Simple Signals

LINEFAIL : OnlineStatus
BATTSTAT : BatteryStatus

In general, each of these directives is required (ecept that the DEVICE directive is ignored for UPSCABLE ether).

None of these directives are required for proper operation of apcupsd. For the Network Information Server to work, it must be enabled in the configuration (default) with --enable-nis

In general, none of these directives are required. However, if you have a voltage-signalling (dumb) UPS with a cable that does not support the Low Battery signal, you must set the TIMEOUT directive to force a shutdown. Please see the Cables section of this manual for more details.

The following directives apply to the master/slave networking mode of apcupsd where multiple machines can be powered by the same UPS. One machine, the master, will have a serial port connection to the UPS, and the other machines, the slaves, will obtain their information via the network from the master.

Note, as of version 3.10.x, the old master/slave code is by default turned off in the configuration. You must explicitly enable it by including a --enable-master-slave option on your ./configure command before building the source.

In addition to the old master/slave code, there is now a new network driver enabled with --enable-net (default disabled) that can be used to control a slave from any version of apcupsd running NIS. This is a much more flexible system of controlling slaves because a slave machine that also has NIS turned on can thus act as a master for another slave with --enable-net turned on. With this mode turned on, the slave obtains the address of the master from the DEVICE directive, which takes the form hostname[:port] as a consequence, none of the directives apply for this form of networking. In addition, for this mode to work, you must specify UPSTYPE net so that the proper driver is loaded.

The remainder of this section presents directives that apply to the old master/slave code that must be enabled by the enable-master-slave configuration option.

The values specified with the following directives are only used if the --configure option is specified on the apcupsd command line, and the UPS is capable of internal EPROM programming. In that case, apcupsd attempts to set the values into the UPSes EPROM.

Under normal operations, the values for these parameters specified in the configuration file are not used. Instead, they are read from the UPS EPROM by apcupsd. See the section called “Configuration Directives Used to Set the UPS EPROM” of this manual for further details before attempting to reprogram your EEPROM.

The STATUS output is in ASCII format with a single data value or piece of information on each line output. Because not all UPSes supply the same information, the output varies based on the type of UPS that you are using. In general, if the information is not available for your UPS, the data portion of the output record will contain an N/A indicating that the information is not available.

Status logging consists of periodically logging ALL available information concerning the UPS. Since the volume of data is rather large (over 1000 bytes per status), the STATUS data is not automatically sent to the system log file, instead, it is written as a series of data records to a specific file (normally /etc/apcupsd/apcupsd.status).

After each write, the file is rewound so that the size of the file remains constant. At the current time, this file is 1135 bytes. The format of this file is very similar to the old apcupsd procfs file. The STATUS file is kept for backward compatibility and will be eliminated in a future version of apcupsd. The preferred method for obtaining this information is from apcaccess or by using the CGI interface.

To make reading the status data reliable via a named pipe, the first record written contains a version number, the number of records that follow the first record, and the total number of bytes in those subsequent records. An actual example of such a status file (/etc/apcupsd/apcupsd.status) is:

Consequently, the first record always consists of 24 bytes (23 characters followed by a newline). This record starts with APC and as indicated in the example above is followed by 28 records consisting of 675 bytes. The last record begins with END APC and contains the date and time matching the DATE record.

Documentation of each record needs to be written. In the coming weeks, I plan to add additional records and possibly change the names of some of the fields.

When this data is written to a file, it is written as two records, the first record, and all the other records together. In reading the file, it can be either be read a record at a time, or in one big read.

When this data is written to syslog(), it is written a record at a time. The first record is the first 24 bytes. By having the number of records and the size in the first record, the complete status can be reliably reassembled.

An example of output from an international SmartUPS 1000 follows:

DATE     : Wed Sep 27 17:30:23 CEST 2000
HOSTNAME : polymatou.sibbald.com
RELEASE  : 3.7.3-20000925
CABLE    : Custom Cable Smart
MODEL    : SMART-UPS 1000
UPSMODE  : Stand Alone
STARTTIME: Wed Sep 27 10:39:23 CEST 2000
UPSNAME  : UPS_IDEN
STATUS   : ONLINE 
LINEV    : 235.3 Volts
LOADPCT  :   9.3 Percent Load Capacity
BCHARGE  : 100.0 Percent
TIMELEFT : 130.0 Minutes
MBATTCHG : 5 Percent
MINTIMEL : 3 Minutes
MAXTIME  : 0 Seconds
MAXLINEV : 239.2 Volts
MINLINEV : 234.0 Volts
OUTPUTV  : 236.6 Volts
SENSE    : High
DWAKE    : 000 Seconds
DSHUTD   : 020 Seconds
DLOWBATT : 02 Minutes
LOTRANS  : 196.0 Volts
HITRANS  : 253.0 Volts
RETPCT   : 000.0 Percent
ITEMP    : 32.8 C Internal
ALARMDEL : 5 seconds
BATTV    : 27.9 Volts
LINEFREQ : 50.0 Hz
LASTXFER : Line voltage notch or spike
NUMXFERS : 0
XONBATT  : N/A
TONBATT  : 0 seconds
CUMONBATT: 0 seconds
XOFFBATT : N/A
SELFTEST : NO
STESTI   : 336
STATFLAG : 0x08 Status Flag
DIPSW    : 0x00 Dip Switch
REG1     : 0x00 Register 1
REG2     : 0x00 Register 2
REG3     : 0x00 Register 3
MANDATE  : 07/31/99
SERIALNO : QS9931125245
BATTDATE : 07/31/99
NOMOUTV  : 230
NOMBATTV :  24.0
HUMIDITY : N/A
AMBTEMP  : N/A
EXTBATTS : 0
BADBATTS : N/A
FIRMWARE : 60.11.I
APCMODEL : IWI
END APC  : Wed Sep 27 17:30:31 CEST 2000

The meaning of the above variables are:

If specified in the configuration file, the STATUS data will also be written to the system log file. Please note, that it would not normally be wise to write this data to a normal system log file as there is no mechanism in syslog() to rewind the file and hence the log file would quickly become enormous. However, in two cases, it can be very useful to use syslog() to write this information.

The first case is to set up your syslog.conf file so that the data is written to a named pipe. In this case, normally not more than about 8192 bytes of data will be kept before it is discarded by the system.

The second case is to setup your syslog.conf file so that the status data is sent to another machine, which presumably then writes it to a named pipe. Consequently, with this mechanism, provides a simple means of networking apcupsd STATUS information.

Although we mention system logging of STATUS information, we strongly recommend that you use apcaccess or the CGI interface to get this information.

If you experienced so problems with the testing procedures, or if you are porting apcupsd to another system, or you are simply curious, you may want to know exactly what is going on during the shutdown process.

The shutdown sequence is as follows:

The above code must be inserted as late as possible in the halt script. On many systems, such as Red Hat, all the disk drives were unmounted, then remounted read-only, thus permitting access to the /etc files and the apcupsd executable. If your system does not explicitly remount the disks, you must remount them in read-only mode in the code that you add. Examples of code fragments that do this can be found in the distributions/suse subdirectory of the source.

If you are not able to insert the above code in your halt script because there is no halt script, or because your halt script calls the init program as some Unix systems do, you can either just forget about powering off the UPS, which means that your machine will not automatically reboot after a power failure, or there is yet another alternative, though not at all as satisfying as inserting code in the halt script.

Only if you cannot insert the appropriate code in the halt script, when you start apcupsd, normally from the /etc/rc.d/init.d/apcupsd script, use the --kill-on-powerfail option. This will cause apcupsd to program the UPS to shutoff the power just before it (apcupsd) does the system shutdown. Please note that this is not the most ideal solution. Read on to understand why.

A very important consideration is that you must set the EEPROM in your UPS so that it waits a sufficient time for the system to halt before it shuts off the UPS power. The current value as well as the permitted values for your UPS can be determined by executing:

apcaccess eeprom

The output should look something like the following:

apcaccess eeprom

Valid EPROM values for the SMART-UPS 1000

                       Config        Current  Permitted
Description              Directive     Value    Values
===================================================================
Upper transfer voltage   HITRANSFER    253      253 264 271 280 
Lower transfer voltage   LOTRANSFER    196      196 188 208 204 
Return threshold         RETURNCHARGE  0        00 15 50 90 
Output voltage on batts  OUTPUTVOLTS   230      230 240 220 225 
Sensitivity              SENSITIVITY   H        H M L L 
Low battery warning      LOWBATT       2        02 05 07 10 
Shutdown grace delay     SLEEP         20       020 180 300 600 
Alarm delay              BEEPSTATE     0        0 T L N 
Wakeup delay             WAKEUP        0        000 060 180 300 
Self test interval       SELFTEST      336      336 168 ON  OFF 

The line of interest for you is the Shutdown grace delay, which can be changed using the SLEEP directive in your apcupsd.conf file. The default value is 20 seconds, but generally, you can set it to 180, 300, or 600 seconds depending on your UPS. See the EEPROM this manual for further details on how to change this EPROM value.

If you use the --kill-on-powerfail option, you run the risk of having the computer power cut before the system has shutdown. Even if the grace period is rather long, if something goes wrong in the shutdown, well, it is up to you to decide.

If apcupsd has successfully shutdown your computer and powered off the UPS during a power outage, you can control whether or not your computer is automatically rebooted when the power returns.

The UPS contains two internal EPROM values that determine when it will restore power to your computer after a full power shutdown. They are the RETURNCHARGE percentage and the WAKEUP delay. Briefly, the RETURNCHARGE specifies what percentage charge the battery must have before the power is restored. Higher values are recommended in regions where the power goes up and down frequently. The WAKEUP delay is a simple time delay. Most sites will have both of these at zero, or perhaps the RETURNCHARGE set to 15. Please follow the links to the Configuration section of this manual for more information. See the EEPROM of this manual for further details on how to change these EPROM values.

Obviously if your halt script is not properly modified, apcupsd will not be able to shut off the power to the UPS, and if the power returns before the batteries are exhausted your system will not automatically reboot. In any case, your machine should have been cleanly shut down.

In master/slave configurations, however, the master cannot be 100 percent sure that the slaves have all shutdown before it performs the power off. As a consequence, it is possible that the master will shut off the power before the slave has finished shutdown. If this is the case, the best procedure is to put an appropriate sleep command in the /etc/apcupsd/apccontrol file on the master. For example to give the slaves 30 additional seconds to shutdown, one would add:

sleep 30

just after the line that reads

doshutdown)

in the apccontrol file (approximately line 79 — depending on your system version).

Also, on a slave machine, you do not want to use the modified halt script since it will recall apcupsd, which will detect that it is a slave (i.e. no connection to the UPS) and will complain that it cannot do the killpower. This situation is not harmful just annoying and possibly confusing.

One possible problem during shutdown can be caused by remnants of old versions. Please be sure to delete or rename all prior versions (/usr/local/sbin/apcupsd or /sbin/powersc).

Normally, apcupsd is automatically started when your system is rebooted. This normally occurs because the startup script apcupsd is linked into the appropriate places in /etc/rc.d. On most Linux systems, there is a program called chkconfig(8) that will automatically link the startup script. This program is invoked by the make install scripts, or it is explicitly done for those systems that do not have chkconfig(8). If this is not the case, you can either link it in appropriately yourself or explicitly call it from your rc.local file. The appropriate manual way to startup apcupsd is by executing:

<path>/apcupsd start

where <path> is normally /etc/rc.d or /etc/rc.d/init.d depending on your system (isn't Unix wonderful? :-)). Using this script is important so that any files remaining around after a power failure are removed. Likewise, shutting down apcupsd should be done with the same script:

<path>/apcupsd stop

Please see the end of Windows chapter of this manual for conderations pertaining to shutdown and killpower on Windows.

Here's the information on the elusive APC smart signaling protocol used by their higher end units (Back-UPS Pro, Smart-UPS, Matrix-UPS, etc). What you see here has been collected from a variety of sources. Some people analyzed the chatter between PowerChute and their hardware. Others sent various characters to the UPS and figured out what the results meant.

Normal 9 pin serial connections have TxD on 3 and RxD on 2. APC's smart serial ports put TxD on pin 1 and RxD on pin 2. This means you go nowhere if you use a normal straight through serial cable. In fact, you might even power down the load if you plug one of those cables in. This is due to the odd routing of pins - DTR and RTS from the PC usually wind up driving the on/off line. So, when you open the port, they go high and *poof* your computer dies.

Originally this evil hack was used to connect the UPS to the PC when this page was first being built. As you can see, I cheated and neglected the ground (only 2 wires!) and it still worked. This method can be used for playing around, but for professional systems this is obviously not a viable option.

That hack didn't work out so well (damned cats), so it was retired quite awhile back. The most practical solution was to go out and BUY the DOS/Win version of PowerChute just for the black (smart) cable. I recommend doing the same thing if you actually care about this thing working properly. Of course, if you have one of the newer packages that came with PowerChute, you already have the cable you need.

If you are handy with cable creation tools, check out the 940-0024C clone diagram. That's the black "smart" cable normally provided with APC models sold after 1996. The loopback pins on that diagram are used to keep PowerChute happy by allowing cable detection. If you use the NUT apcsmart driver, those pins don't matter.

Many thanks to Steve Draper for providing this scan.

For additional information on cables, see the section on custom cables in this manual.

Despite the lack of official information from APC, this table has been constructed. It's standard RS-232 serial communications at 2400 bps/8N1. Don't rush the UPS while transmitting or it may stop talking to you. This isn't a problem with the normal single character queries, but it really does matter for multi-char things like "@000". Sprinkle a few calls to usleep() in your code and everything will work a lot better.

The following table describes the single character Code or command that you can send to the UPS, its meaning, and what sort of response the UPS will provide. Typically, the response shown below is followed by a newline (\n in C) and a carriage return (\r in C). If you send the UPS a command that it does not recognize or that is not available on your UPS, it will normally respond by "NA" for not available, otherwise the response is given in the "Typical results" column. >

This is probably the most important register of the UPS, which indicates the overall UPS status. Some common things you'll see:

These single character messages are sent by the UPS any time there is an Alert condition. All other responses indicated above are sent by the UPS only in response to a query or action command.

All bits are valid on the Matrix UPS. SmartUPS models only support bits 6 and 7. Other models do not respond.

Matrix UPS models report bits 0-5. SmartUPS models only support bits 4 and 6. SmartUPS v/s and BackUPS Pro report bits 4, 6, 7. Unused bits are set to 0. Other models do not respond.

All bits are valid on the Matrix UPS and 3rd generation SmartUPS models. SmartUPS v/s and BackUPS Pro models report bits 0-5. All others report 0-4. State change of bits 1,2,5,6,7 are reported asynchronously with ? and = messages.

The Old Firmware Revision is obtained with the "V" command, which gives a typical response such as "GWD" or "IWI", and can be interpreted as follows:

Old Firmware revision and model ID String for SmartUPS & MatrixUPS

This is a three character string XYZ

   where X == Smart-UPS or Matrix-UPS ID Code.
     range 0-9 and A-P
       1 == unknown
       0 == Matrix 3000
       5 == Matrix 5000
     the rest are Smart-UPS and Smart-UPS-XL
       2 == 250       3 == 400       4 == 400
       6 == 600       7 == 900       8 == 1250
       9 == 2000      A == 1400      B == 1000
       C == 650       D == 420       E == 280
       F == 450       G == 700       H == 700XL
       I == 1000      J == 1000XL    K == 1400
       L == 1400XL    M == 2200      N == 2200XL
       O == 3000      P == 5000

   where Y == Possible Level of Smart Features, unknown???
       G == Stand Alone
       T == Stand Alone
               V == ???
       W == Rack Mount

   where Z == National Model Use Only Codes
       D == Domestic        115 Volts
       I == International   230 Volts
       A == Asia ??         100 Volts
       J == Japan ??        100 Volts

New Firmware revison and model ID String in NN.M.L is the format

    where NN == UPS ID Code.
        12 == Back-UPS Pro 650
        13 == Back-UPS Pro 1000
        52 == Smart-UPS 700
        60 == SmartUPS 1000
        72 == Smart-UPS 1400

        where NN now Nn has possible meanings.
            N  == Class of UPS
            1n == Back-UPS Pro
            5n == Smart-UPS
            7n == Smart-UPS NET

             n == Level of intelligence
            N1 == Simple Signal, if detectable WAG(*)
            N2 == Full Set of Smart Signals
            N3 == Micro Subset of Smart Signals

    where M == Possible Level of Smart Features, unknown???
        1 == Stand Alone
        8 == Rack Mount
        9 == Rack Mount

    where L == National Model Use Only Codes
        D == Domestic        115 Volts
        I == International   230 Volts
        A == Asia ??         100 Volts
        J == Japan ??        100 Volts
        M == North America   208 Volts (Servers)

Upon sending a ^Z, your UPS will probably spit back approximately 254 characters something like the following (truncated here for the example):

#uD43132135138129uM43229234239224uA43110112114108 ....

It looks bizarre and ugly, but is easily parsed. The # is some kind of marker/ident character. Skip it. The rest fits this form:

Matrix-UPS models have ## between each grouping for some reason.

Here is an example broken out to be more readable:

 CMD DFO RSP FSZ FVL
 u   D   4   3   127 130 133 136
 u   M   4   3   229 234 239 224
 u   A   4   3   108 110 112 114
 u   I   4   3   253 257 261 265
 l   D   4   3   106 103 100 097
 l   M   4   3   177 172 168 182
 l   A   4   3   092 090 088 086
 l   I   4   3   208 204 200 196
 e   4   4   2   00   15  50  90
 o   D   1   3   115
 o   J   1   3   100
 o   I   1   3   230 240 220 225
 o   M   1   3   208
 s   4   4   1     H   M   L   L
 q   4   4   2    02  05  07  10
 p   4   4   3   020 180 300 600
 k   4   4   1     0   T   L   N
 r   4   4   3   000 060 180 300
 E   4   4   3   336 168  ON OFF

 CMD == UPSlink Command.
       u = upper transfer voltage
       l = lower transfer voltage
       e = return threshold
       o = output voltage
       s = sensitivity
       p = shutdown grace delay
       q = low battery warning
       k = alarm delay
       r = wakeup delay
       E = self test interval

 DFO == (4)-all-countries (D)omestic (I)nternational (A)sia (J)apan
        (M) North America - servers.
 RSP == Total number possible answers returned by a given CMD.
 FSZ == Max. number of field positions to be filled.
 FVL == Values that are returned and legal.

There are at this time a maximum of 12 different values that can be programmed into the UPS EEPROM. They are:

The first two cases (Ident and Batt date) are somewhat special in that you tell the UPS you want to change the value, then you supply 8 characters that are saved in the EEPROM. The last ten item are programmed by telling the UPS that you want it to cycle to the next permitted value.

In each case, you indicate to the UPS that you want to change the EEPROM by first sending the appropriate query command (e.g. "c" for the UPS ID or "u" for the Upper Transfer voltage. This command is then immediately followed by the cycle EEPROM command or "-". In the case of the UPS Id or the battery date, you follow the cycle command by the eight characters that you want to put in the EEPROM. In the case of the other ten items, there is nothing more to enter.

The UPS will respond by "OK" and approximately 5 seconds later by a vertical bar (|) to indicate that the EEPROM was changed.

The apcupsd has a rather long and tormented history. Many thanks to the guys that, with time, contributed to the general public knowledge.

Pavel Korensky <pavelk at dator3.anet.cz>, Andre M. Hedrick <hedrick at suse.de>, Christopher J. Reimer <reimer at doe.carleton.ca>, Kevin D. Smolkowski <kevins at trigger.oslc.org>, Werner Panocha <wpanocha at t-online.de>, Steven Freed, Russell Kroll.

additions by: Kern Sibbald <apcupsd-users at lists.sourceforge.net>