Linux: Configure and Control APC SmartUPS During a Power Failure

by on July 29, 2012 · 11 comments· LAST UPDATED November 18, 2012

in ,

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
DifficultyIntermediate (rss)
Root privilegesYes
RequirementsAPC ups with cable
Estimated completion timeN/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:

Check out related media

This tutorial also available in video format:

(Video.01: Installing apc usp under Debian / Ubuntu Linux. Can't view video? Click here.)

References
  • APCUPSD project.
  • man page - apcupsd, apt-get, and yum command.
TwitterFacebookGoogle+PDF versionFound an error/typo on this page? Help us!

{ 11 comments… read them below or add one }

1 Mark Preston August 1, 2012 at 1:45 am

Is there a way to do the server config easily? I’m not understanding that part of this. But the panel has a XFCE-power-manager 1.0.11 on the panel. apcaccess returns nada in the termnal.

mark@Lexington-19:~$ apctest
2012-07-31 18:27:10 apctest 3.14.10 (13 September 2011) debian
Checking configuration ...
Terminating due to configuration file errors.
apctest error termination completed
mark@Lexington-19:~$ apcaccess
Error contacting apcupsd @ localhost:3551: Connection refused
mark@Lexington-19:~$ tail -f /var/log/apcupsd.events
tail: cannot open `/var/log/apcupsd.events' for reading: No such file or directory
mark@Lexington-19:~$ /etc/init.d/apcupsd start
Starting UPS power management: Terminating due to configuration file errors.
mark@Lexington-19:~$ /etc/init.d/apcupsd stop
Stopping UPS power management: No process in pidfile '/var/run/apcupsd.pid' found running; none killed.
apcupsd.
mark@Lexington-19:~$ /etc/init.d/apcupsd restart
Stopping UPS power management: No process in pidfile '/var/run/apcupsd.pid' found running; none killed.
apcupsd.
Starting UPS power management: Terminating due to configuration file errors.
mark@Lexington-19:~$ /var/log/messages
bash: /var/log/messages: No such file or directory
mark@Lexington-19:~$

Reply

2 nixCraft August 23, 2012 at 12:53 pm

You need to run command as root. USe sudo before command names:

sudo command-name

Also check your config file as it has some errors.

Reply

3 Mickael August 3, 2012 at 9:44 am

That’s awesome, thank you for this greet post.
Mickael

Reply

4 Nico Bos February 8, 2013 at 3:09 pm

This was very helpfull!

First I tried the APC PowerChute. But it just doesn’t seem to work with USB.
Then I found your post and my problems were solved.
Thanks!

Reply

5 Al Unser Jr. June 13, 2013 at 7:51 pm

Thx a lot!

Reply

6 Mike Burr December 7, 2013 at 5:58 pm

On newer versions of Fedora (16+?), systemctl is preferred over /etc/init.d scripts and chkconfig. Here are the commands that worked for me:

# cat /etc/fedora-release
Fedora release 19 (Schrödinger’s Cat)
# yum list apcupsd
Loaded plugins: langpacks, refresh-packagekit
Installed Packages
apcupsd.x86_64                                                  3.14.10-10.fc19                                                  @fedora 

And:

# systemctl enable apcupsd.service
ln -s '/usr/lib/systemd/system/apcupsd.service' '/etc/systemd/system/multi-user.target.wants/apcupsd.service'
# systemctl start apcupsd.service
# systemctl status apcupsd.service
apcupsd.service - APC UPS Power Control Daemon for Linux
   Loaded: loaded (/usr/lib/systemd/system/apcupsd.service; enabled)
   Active: active (running) since Sat 2013-12-07 12:54:41 EST; 30s ago
  Process: 2047 ExecStartPre=/bin/rm -f /etc/apcupsd/powerfail (code=exited, status=0/SUCCESS)
 Main PID: 2049 (apcupsd)
   CGroup: name=systemd:/system/apcupsd.service
           └─2049 /sbin/apcupsd -b -f /etc/apcupsd/apcupsd.conf
Dec 07 12:54:41 pinot-noir systemd[1]: Starting APC UPS Power Control Daemon for Linux...
Dec 07 12:54:41 pinot-noir systemd[1]: Started APC UPS Power Control Daemon for Linux.
Dec 07 12:54:42 pinot-noir apcupsd[2049]: apcupsd 3.14.10 (13 September 2011) redhat startup succeeded
Dec 07 12:54:42 pinot-noir apcupsd[2049]: NIS server startup succeeded

Reply

7 svm December 18, 2013 at 3:25 am

hi,

what if were using the rj45 cable (Cat5) for the smart ups connected to the switch. what will we define the type of cable connecting the UPS to your Linux serve?

thanks

Reply

8 svm December 18, 2013 at 8:57 am

this set-up is only for one smartups.. what if we have two smart ups..how do we configure it? thanks

Reply

9 Jawaad April 23, 2014 at 4:18 pm

Thank you it work for Powerchute OS Ubuntu 10.04
Great post!

Reply

10 Wen August 29, 2014 at 5:42 pm

This is very helpful! Thanks!

Reply

11 Shaun October 27, 2014 at 5:13 pm

As svm mentioned last December, this handles one UPS. I have two – one for each power supply. How do we set things up to handle this use case?

Reply

Leave a Comment

Tagged as: , , , , , , , , , , , , , , , , , , , ,

Previous Faq:

Next Faq: