Linux: Configure and Control APC SmartUPS During a Power Failure

My Linux nas server connected to APC SmartUPS using usb cable and I would like to detect a power failure. If power is not restored my server must shutdown when the battery is exhausted. How do I configure and use my APC SmartUPS under Debina / Ubuntu / RHEL / CentOS / Fedora / Scientific Linux operating system for power management?

Tutorial details
Difficulty	Intermediate (rss)
Root privileges	Yes
Requirements	APC ups with cable
Estimated completion time	N/A

Linux comes with GPL licensed open source apcupsd server ( daemon ) that can be used for power mangement and controlling most of APC's UPS models on Linux, BSD, Unix and MS-Windows operating systems. Apcupsd works with most of APC's Smart-UPS models as well as most simple signalling models such a Back-UPS, and BackUPS-Office. During a power failure, apcupsd will inform the users about the power failure and that a shutdown may occur. If power is not restored, a system shutdown will follow when the battery is exhausted, a timeout (seconds) expires, or runtime expires based on internal APC calculations determined by power consumption rates.

Step #1: Install Apcupsd

Type the following apt-get command under Debian / Ubuntu Linux install apcupsd software:
# apt-get install apcupsd
Sample outputs:

Reading package lists... Done
Building dependency tree
Reading state information... Done
Suggested packages:
  apcupsd-cgi hal
The following NEW packages will be installed:
  apcupsd
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
Need to get 0 B/291 kB of archives.
After this operation, 672 kB of additional disk space will be used.
Selecting previously deselected package apcupsd.
(Reading database ... 30840 files and directories currently installed.)
Unpacking apcupsd (from .../apcupsd_3.14.8-2_amd64.deb) ...
Processing triggers for man-db ...
Setting up apcupsd (3.14.8-2) ...
update-rc.d: warning: apcupsd start runlevel arguments (1 2 3 4 5) do not match LSB Default-Start values (2 3 4 5)
update-rc.d: warning: apcupsd stop runlevel arguments (0 6) do not match LSB Default-Stop values (0 1 6)
Please check your configuration ISCONFIGURED in /etc/default/apcupsd

Edit /etc/default/apcupsd, enter:
# vi /etc/default/apcupsd
Set ISCONFIGURED to yes:
ISCONFIGURED=yes
Save and close the file. If you are using RHEL / CentOS Linux use yum command as follows, enter:
# yum install apcupsd
Sample outputs:

 
Loaded plugins: product-id, protectbase, rhnplugin, subscription-manager
Updating certificate-based repositories.
Unable to read consumer identity
0 packages excluded due to repository protections
Setting up Install Process
Resolving Dependencies
--> Running transaction check
---> Package apcupsd.x86_64 0:3.14.10-1.el6 will be installed
--> Finished Dependency Resolution
 
Dependencies Resolved
 
====================================================================================================
 Package               Arch                 Version                        Repository          Size
====================================================================================================
Installing:
 apcupsd               x86_64               3.14.10-1.el6                  epel               299 k
 
Transaction Summary
====================================================================================================
Install       1 Package(s)
 
Total download size: 299 k
Installed size: 1.3 M
Is this ok [y/N]: y
Downloading Packages:
apcupsd-3.14.10-1.el6.x86_64.rpm                                             | 299 kB     00:00
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
  Installing : apcupsd-3.14.10-1.el6.x86_64                                                     1/1
Installed products updated.
  Verifying  : apcupsd-3.14.10-1.el6.x86_64                                                     1/1
 
Installed:
  apcupsd.x86_64 0:3.14.10-1.el6
 
Complete!

Step 2: Connect UPS

You need to connect the UPS to your server using cable. You will see the following entry in /var/log/messages

Jul 28 14:11:18 nas02 kernel: [    3.060349] usb 2-1: Product: Back-UPS RS 1500 FW:8.g9a.I USB FW:g9a
Jul 28 14:11:18 nas02 kernel: [    5.348979] generic-usb 0003:051D:0002.0001: hiddev0,hidraw0: USB HID v1.10 Device [American Power Conversion Back-UPS RS 1500 FW:8.g9a.I USB FW:g9a] on usb-0000:00:10.0-1/input0

Step #3: Configure UPS

Edit /etc/apcupsd/apcupsd.conf, enter:
# vi /etc/apcupsd/apcupsd.conf
First, give your UPS a name. This is particulary useful if you have multiple UPSes. This does not set the EEPROM. It should be 8 characters or less:

 
UPSNAME homeups1

Next, defines the type of cable connecting the UPS to your Linux server. In this example, I'm connecting my UPS using usb:

 
UPSCABLE usb

Possible generic choices for cable are - simple, smart, ether, and usb. Or a specific cable model number may be used such as 940-0119A. For USB UPSes, please leave the DEVICE directive blank. For
other UPS types, you must specify an appropriate port or address (see config file):

## set ups type to usb ##
UPSTYPE usb
DEVICE

Configuration parameters used during power failures

The ONBATTERYDELAY directive defined the time in seconds from when a power failure s detected until we react to it with an onbattery event:

 
ONBATTERYDELAY 6

If during a power failure, the remaining battery percentage (as reported by the UPS) is below or equal to BATTERYLEVEL, apcupsd will initiate a Linux system shutdown:

 
BATTERYLEVEL 5

If during a power failure, the remaining runtime in minutes (as calculated internally by the UPS) is below or equal to MINUTES, apcupsd, will initiate a system shutdown.

 
MINUTES 3

If during a power failure, the UPS has run on batteries for TIMEOUT many seconds or longer, apcupsd will initiate a system shutdown. A value of 0 disables this timer:

 
TIMEOUT 0

Note: If you have an older dumb UPS, you will want to set this to less than the time you know you can run on batteries.

Configuration apcupsd network information server

You can use CGI or GUI programs from remote system to get information about your UPS. Turn on network information server:

 
NETSERVER on

Set IP address on which NIS server will listen for incoming connections. You need to configure this setting to any specific IP address of your server and NIS will listen for connections only on that interface. Use the loopback address (127.0.0.1) to accept connections only from the local machine (default).

 
NISIP 127.0.0.1
### example - for lan users ###
# NISIP 192.168.1.11
###############################

The default port is set to 3551for sending STATUS and EVENTS data over the network:

 
NISPORT 3551

Save and close the file.

Step #4: Test ups

Type the following command:
# apctest
Sample outputs:

 
2012-07-29 16:52:40 apctest 3.14.8 (16 January 2010) debian
Checking configuration ...
Attached to driver: usb
sharenet.type = DISABLE
cable.type = USB_CABLE
 
You are using a USB cable type, so I'm entering USB test mode
mode.type = USB_UPS
Setting up the port ...
Hello, this is the apcupsd Cable Test program.
This part of apctest is for testing USB UPSes.
 
Getting UPS capabilities...SUCCESS
 
Please select the function you want to perform.
 
1)  Test kill UPS power
2)  Perform self-test
3)  Read last self-test result
4)  View/Change battery date
5)  View manufacturing date
6)  View/Change alarm behavior
7)  View/Change sensitivity
8)  View/Change low transfer voltage
9)  View/Change high transfer voltage
10) Perform battery calibration
11) Test alarm
12) View/Change self-test interval
 Q) Quit
 
Select function number:

You can test your ups or read test results.

How do I start apcupsd server?

Type the following command to start / stop / restart service:
# /etc/init.d/apcupsd start # /etc/init.d/apcupsd stop # /etc/init.d/apcupsd restart
RHEL / CentOS / Red Hat / Fedora Linux can use the same command. However, you need to turn on service on boot:
# chkconfig apcupsd on

How do I see current status of my UPS?

Type the following command:
# apcaccess
Sample outputs:

APC      : 001,037,0952
DATE     : 2012-07-29 16:58:36 +0530
HOSTNAME : nas02.nixcraft.net.in
VERSION  : 3.14.8 (16 January 2010) debian
UPSNAME  : nas02.nixcraft.net.in
CABLE    : USB Cable
MODEL    : Back-UPS RS 1500 
UPSMODE  : Stand Alone
STARTTIME: 2012-07-29 16:58:34 +0530
STATUS   : ONLINE
LINEV    : 226.0 Volts
LOADPCT  :  11.0 Percent Load Capacity
BCHARGE  : 100.0 Percent
TIMELEFT : 283.5 Minutes
MBATTCHG : 5 Percent
MINTIMEL : 3 Minutes
MAXTIME  : 0 Seconds
SENSE    : Medium
LOTRANS  : 194.0 Volts
HITRANS  : 264.0 Volts
ALARMDEL : Always
BATTV    : 26.9 Volts
LASTXFER : Automatic or explicit self test
NUMXFERS : 0
TONBATT  : 0 seconds
CUMONBATT: 0 seconds
XOFFBATT : N/A
SELFTEST : OK
STATFLAG : 0x07000008 Status Flag
MANDATE  : 2007-07-26
SERIALNO : XYZYYZAAB
BATTDATE : 2007-07-26
NOMINV   : 230 Volts
NOMBATTV :  24.0 Volts
NOMPOWER : 865 Watts
FIRMWARE : 8.g9a.I USB FW:g9a
APCMODEL : Back-UPS RS 1500
END APC  : 2012-07-29 16:58:39 +0530

How do I view ups events such as power failure?

The UPS status is logged in /var/log/apcupsd.events file. To view this file, enter:
# tail -f /var/log/apcupsd.events
Sample outputs:

2012-07-29 03:36:21 +0530  apcupsd 3.14.8 (16 January 2010) debian startup succeeded
2012-07-29 03:38:06 +0530  apcupsd exiting, signal 15
2012-07-29 03:38:06 +0530  apcupsd shutdown succeeded
2012-07-29 03:49:54 +0530  apcupsd 3.14.8 (16 January 2010) debian startup succeeded
2012-07-29 07:08:52 +0530  Power failure.
2012-07-29 07:08:54 +0530  Power is back. UPS running on mains.
2012-07-29 11:24:32 +0530  Power failure.
2012-07-29 11:24:35 +0530  Power is back. UPS running on mains.
2012-07-29 14:34:43 +0530  Power failure.
2012-07-29 14:34:47 +0530  Power is back. UPS running on mains.

A note about desktop GUI monitoring tool

Gapcmon is a desktop monitor program for the apcupsd server. You can install it using the following command:
# apt-get install gapcmon
OR use yum command for RHEL / CentOS Linux:
# yum install apcupsd-gui
Run it as follows:
$ gapcmon

A note about web based monitoring tool

You can install a package called apcupsd-cgi so that you can monitor your UPS load, uptime, logs and other details using www. Type the following apt-get command to install the same:
# apt-get install apcupsd-cgi
OR use yum command for RHEL / CentOS Linux:
# yum install apcupsd-cgi
You need to configure Apache web server with cgi-bin or lighttpd server with cgi-bin server. Once configured, type the url as follows using any web-browser:
http://server-ip/cgi-bin/apcupsd/multimon.cgi
Sample outputs from both desktop and web-base gui monitor tools: