Linux Power Line Monitor

Overview

This document describes how to set up a Linux computer with apcupsd connected to an APC uninterruptible power supply to monitor the state of the AC powerline. The voltage is plotted on a web page and email or telephone alarms can be sent to anyone concerned about power fluctuations.

Hardware connections

The APC UPS uses a nonstandard cable (940-0024C) that resembles a serial cable. However, if you attach a standard serial cable to the APC, the UPS will shut off as soon as the cable is attached to a computer. It is possible that some newer UPS models no longer have this feature.

APC 940-0024C UPS Cable
APC 9400024c

Installation of apcupsd

This information is taken from the 195-page apcupsd manual written by Kern Sibbald and applies to apcupsd version 3.10.17. The manual should be consulted for authoritative or complete information.

It is recommended to plug your computer into the wall instead of the UPS when testing, because APC UPSs will shut down if the wrong cable is attached, if you make a configuration mistake, or if you send certain characters out the serial port during testing.

  1. Build apcupsd 
    ./configure --prefix=/usr --sbindir=/sbin --enable-usb \
--enable-cgi --with-cgi-bin=/usr/local/httpd/cgi-bin \
--enable-pthreads
    (omit enable-usb if your UPS uses a pseudo-serial or serial cable) 
    make
su
/etc/rc.d/apcupsd stop  (to stop any running instance of apcupsd)
  2. Uninstall any old apcupsd-related files
    • locate apcupsd or whereis apcupsd followed by rm
    • remove old apctest
    • remove old apcupsd
    • remove old /etc/apcups.d
    • remove old acpaccess
    • remove old apcnisd
  3. Install apcupsd 
    cp /etc/rc.d/halt /etc/rc.d/halt.bak
  (or /etc/rc.d/init.d/halt in Red Hat)
make install
  4. Edit /etc/apcupsd/apcupsd.conf
    • UPSTYPE - set to dumb, apcsmart, smartups usb, net, snmp, or ether
    • UPSCABLE - set to the cable type = smart
    • DEVICE /dev/ttyS0
    • if you have a USB UPS, comment out DEVICE
    • UPSMODE disable
    • NETSERVER on
    • NISIP 63.127.146.192
    • NISPORT 3551
    • EVENTSFILE /var/log/apcupsd.events
    • STATTIME 60
    • STATFILE /var/log/apcupsd.status
    • MONITOR endive "The Server"
  5. Check /etc/rc.d/halt script to make sure it was properly updated.
  6. Start apcupsd with /etc/rc.d/apcupsd start (etc/rc.d/init.d/apcupsd start in Red Hat)

Communicating with the UPS

The file /var/log/apcupsd.status is updated once per minute. Different UPSs provide different amounts of information. The Smart-UPS 1000 gives the following: 
APC      : 001,052,1230
DATE     : Fri Aug 19 17:30:57 EDT 2005
HOSTNAME : endive
RELEASE  : 3.10.18
VERSION  : 3.10.18 (21 July 2005) suse
UPSNAME  : UPS_IDEN
CABLE    : APC Cable 940-0024C
MODEL    : SMART-UPS 1000
UPSMODE  : Stand Alone
STARTTIME: Fri Aug 19 17:21:22 EDT 2005
STATUS   : ONLINE 
LINEV    : 117.6 Volts
LOADPCT  :  76.4 Percent Load Capacity
BCHARGE  : 100.0 Percent
TIMELEFT :  17.0 Minutes
MBATTCHG : 5 Percent
MINTIMEL : 3 Minutes
MAXTIME  : 0 Seconds
MAXLINEV : 118.9 Volts
MINLINEV : 117.0 Volts
OUTPUTV  : 117.6 Volts
SENSE    : High
DWAKE    : 000 Seconds
DSHUTD   : 020 Seconds
DLOWBATT : 02 Minutes
LOTRANS  : 103.0 Volts
HITRANS  : 132.0 Volts
RETPCT   : 000.0 Percent
ITEMP    : 35.1 C Internal
ALARMDEL : 5 seconds
BATTV    : 27.7 Volts
LINEFREQ : 60.0 Hz
LASTXFER : Automatic or explicit self test
NUMXFERS : 0
TONBATT  : 0 seconds
CUMONBATT: 0 seconds
XOFFBATT : N/A
SELFTEST : NO
STESTI   : 336
STATFLAG : 0x02000008 Status Flag
DIPSW    : 0x00 Dip Switch
REG1     : 0x00 Register 1
REG2     : 0x00 Register 2
REG3     : 0x00 Register 3
MANDATE  : 05/24/00
SERIALNO : QS0022213176
BATTDATE : 05/24/00
NOMOUTV  : 115
NOMBATTV :  24.0
EXTBATTS : 0
FIRMWARE : 60.11.D
APCMODEL : IWD
END APC  : Fri Aug 19 17:30:59 EDT 2005
Typing "apcaccess status" gives the same information"; for example; 
apcacces status sendive:3551
Make sure NISIP is to an appropriate subnet mask, or people on the Internet may start trying to hack into your UPS. The utility "apctest" enters interactive mode, allowing you to perform various tests, including battery runtime calibration.

Make sure cgi is enabled in your web server.

Edit /etc/apcupsd/hosts.conf and add a line for each computer running upsd. This is used by multimon to monitor multiple UPSs and by upsstats to provide information.

Getting the information on your web page

Apcupsd creates nice graphs, giving a useful visual indication of the current status. It would be even more useful if the information provided by the UPS were accurate, but I guess we can't have everything. All that is necessary is to put the cgi files in the server's cgi-bin directory and enable cgi (ExecCGI) in httpd.conf. We used soft links to the event data file to avoid having to re-configure apcupsd. If this is done, be sure to configure the server to allow soft links to locations outside the httpd directory (FollowSymLinks). The files we use are:

Put links to these files in your html file.

Using APCUPSD as an alarm system

In some situations, it's desirable to disable the shutdown feature of apcupsd, and use it as an alarm system. For example, your server might be connected to an emergency generator, but you want to send emails or text messages in the event of a power failure. This is easy.

The server would be set up with two UPSs as shown. The server is powered by one UPS, which is connected to the generator (red faceplate). A UPS is still necessary because the generator usually takes ten seconds to kick in. The UPS control cable comes from a cheap, low-capacity SmartUPS which is plugged into an ordinary outlet (gray faceplate). Its sole purpose is to provide voltage readings. You could also connect the signal cable from UPS #2 to provide low-battery warnings.

The convention is that emergency power outlets are red and ordinary ones are gray. Some buildings also have orange outlets. These are usually a special type of power such as power connected to a low-impedance ground for sensitive equipment. Don't use the orange ones.

UPS configuration for alarm

UPS #1 monitors the voltage, but instead of shutting down the server, it sends text messages to everyone. This is done by changing the software to call a simple script like the following: 
#!/bin/sh
logger Sending emails 
/bin/mail somebody@someplace.org -r apcupsd < /home/somebody/powerfailure.txt
logger Sending text messages 
/bin/mail 3015551212@text.att.net < /home/somebody/powerfailure.txt

The -r option sets the Sender to the apcupsd user if you have one. This helps ensure they will read the email right away.

All that is necessary is to modify the /etc/apcupsd/apccontrol script. The manual recommends changing apccontrol.sh.in and re-running configure. This is the preferred way if you build apcupsd from source. If not, you will have to change the script so instead of calling /sbin/shutdown, it calls your script. Just remember, if you ever re-install apcupsd, the apccontrol script will be overwritten.

Back