Friday, June 1, 2012

Debian APC UPS client-server monitoring

Apcupsd is a UPS control system that permits orderly shutdown of your computer in the event of a power failure. We will take a look at NIS (Network Information Server) server and client configuration (this is the case when a single UPS powers several computers).

Server

NIS (Network Information Server) mode allows communication between different hosts. Only one of those hosts, the server, needs to talk to the UPS directly.
  1. Ensure device is connected and recognized. In most cases your UPS is connected to server via USB cable. In Linux you can check this by listing USB devices (provided by usbhid driver):
    deby1:~# ls /dev/usb/
    hiddev0
    
    If your device is no connected, most likely, you will get a message like this:
    ls: cannot access /dev/usb/: No such file or
    directory
    
    Note, in our case the UPS device is available at /dev/usb/hiddev0.
  2. Install UPS monitoring software. Apcupsd is a software designed to control APC UPS devices, let get it installed:
    apt-get install apcupsd
    
  3. Configure apcupsd. Ensure the following settings (file /etc/apcupsd/apcupsd.conf):
    UPSCABLE usb
    
    UPSTYPE  usb
    DEVICE   /dev/usb/hiddev0
    
    NISIP    0.0.0.0
    
    Let apcupsd daemon know it is configured (file /etc/default/apcupsd):
    ISCONFIGURED=yes
    
  4. Start apcupsd service:
    /etc/init.d/apcupsd start
    
    Check UPS status:
    apcaccess status <server name>
    
    Take a look at any errors reported (file /var/log/apcupsd.events):
    ...  apcupsd 3.14.10 (...) debian startup succeeded
    

Client

The client computer will communicate with server via network.
  1. Install UPS monitoring software.
    apt-get install apcupsd
    
  2. Configure apcupsd. Ensure the following settings (file /etc/apcupsd/apcupsd.conf):
    UPSCABLE ether
    
    UPSTYPE net
    #DEVICE  hostname:port
    DEVICE  deby1.dev.local:3551
    
    NETSERVER off
    
    Let apcupsd daemon know it is configured (file /etc/default/apcupsd):
    ISCONFIGURED=yes
    
  3. Start apcupsd service:
    /etc/init.d/apcupsd start
    

Notifications

You are able receive a number of notification events, e.g. power failure, etc (see a complete list of events here). By default apcupsd calls script located at /etc/apcupsd/apccontrol. This script echo some events to user console, as well as shuts down host per doshutdown event. You can easily extend this script to email you events. Here is the script (file /usr/local/sbin/notify.sh):
#!/bin/sh

domain=`hostname -d`
mail=root@$domain
msg=Test

if [ ! -z "$2" ]; then
    mail=$1; msg=$2
    if ! echo $mail | grep -q "$domain"; then
        mail=$mail@$domain
    fi
else
    if [ ! -z "$1" ]; then msg=$1; fi
fi

# strip whitespace at the end of message
msg=`echo "$msg" | sed 's/ *$//g'`

echo $msg | mail -s "$msg" $mail
echo $msg | wall
Ensure the following in apc event handler (file /etc/apcupsd/apccontrol):
#WALL=wall
WALL="xargs -0 notify.sh ups@dev.local"
This will email all events handled by apccontrol to ups@dev.local.