PROGRAMMING Perl: Uninterruptible Power Supply

Power through power outages

PROLONGED LIFE

An uninterruptible power supply can help get you through a short power outage without los-

ELEN, fotolia
ing data or damaging hardware. A Nagios script written in Perl checks UPS health and initi-
ates a controlled powerdown if the unit exhausts its battery capacity. BY MICHAEL SCHILLI

W
hile going through my drawers
full of old computer hardware,
I found a cheap, old, uninter-
ruptible power supply (UPS). I must
have bought it because it was on sale,
since the “Cyberpower 325SL” only pro-
vides 185 watts for about five minutes.
But I figured that’s good enough for
helping a desktop PC, a DSL modem,
and a router go through a short power
outage unharmed.
Send Like It’s 1999
The UPS features a serial interface jack
(Figure 1) that can be connected to a PC
with a serial cable. That’s what I call
retro! The unit also came with Windows-
only software that I remember discard-
ing way back, right after opening the
package. When searching the web, how-
ever, I found the NUT project [1], which
offers drivers for all kinds of UPS sys-
tems and a daemon to communicate
with the UPS unit through the drivers.
Installing the NUT software was a
breeze; the documentation that came
with the distribution is stellar. After
compiling and running make install,
three configuration files must be created.
First, the ups.conf file sets the parame-
ters for the UPS used (Figure 2). In my
case, I chose the genericups driver,
which works with cheap UPS units and
just provides basic online/offline status
without fancy UPS stats or battery ca-
pacity left. Looking at the driver docu-
mentation revealed that, for CyberPower
units, “type 7” has to be used. I called
the device “elcheapo,” and that’s how it
is going to be referenced later on when
its status is checked.
Because I plugged the serial cable into
the second serial port of my PC, the con-
figured port is /dev/ttyS1. Had I plugged
it into the first serial jack, /dev/ttyS0
would have been the port.
Limit Access
The daemon configuration file upsd.conf
defines rules on who can access the UPS
data from the NUT daemon (Figure 3). I
opened the file for my PC’s static IP ad-
dress, and the /32 at the end defines that
only status data can be read.
For home use, defining user-based ac-
cess via upsd.users is probably overkill,
but the file needs to be there, so an
empty file will do.
You could define a new user “nut”
with an associated group, but I decided
to let the daemon run as the default user
nobody, on whose behalf we need to cre-
ate a state directory:
# mkdir /var/state/ups
# chown nobody /var/state/ups

74 ISSUE 80 JULY 2007 W W W. L I N U X - M A G A Z I N E . C O M


Figure 1: The UPS system with two power plugs on top and one serial cable plugged in on the
right. The “Kill-A-Watt” meter indicates that PC, DSL modem, and router combined are using
about 114 watts.
# chmod 700 /var/state/ups
Next, the driver daemon and then the
NUT daemon must be started as root:
# /usr/local/ups/bin/U
upsdrvctl start
# /usr/local/ups/sbin/upsd
If the output from these commands indi-
cates success, a quick test with the upsc
utility (which comes with NUT) will re-
veal that the UPS is online, drawing juice
from the power outlet:
$ upsc elcheapo@localhostU
ups.status
OL
When unplugging the UPS so that it
powers the PC from its battery, the
01 #!/usr/bin/perl
02 #############################
03 # check_myups
04 # Mike Schilli, 2007
05 #############################
06 use strict;
07 use Log::Log4perl qw(:easy);
08 use Nagios::Clientstatus;
09
10 my $version = "0.01";
11 my $ncli = 22 chomp $data;
12 Nagios::Clientstatus->new(
Perl: Uninterruptible Power Supply
above upsc call will return OB instead of
returning OL.
Over in Nagios Land
How should you monitor the UPS? Regu-
lar readers will remember that I’ve
talked about Nagios in this column be-
fore [2]. Nagios watches over all kinds
of systems in my home, including room
temperature, hard-disk capacity, and the
performance of the hosting service I’m
using for my websites. So, I decided to
add a UPS watcher as just another Nag-
ios task to my existing setup (Figure 4).
The script in Listing 1, check_myups,
uses the upsc utility mentioned above to
query the UPS status but adds a wrapper
so that the script can be used as a Nag-
ios plugin. It uses a few extra Perl mod-
ules, which can be downloaded from
CPAN. If the UPS is up and the check
Listing 1: check_myups
13 help_subref => sub {
14 print "usage: $0\n";
15 },
16 version => $version,
17 mandatory_args => [],
18 );
19
20 my $data = `upsc elcheapo\
@localhost ups.status`;
21
23 my $status = "ok";
W W W. L I N U X - M A G A Z I N E . C O M
PROGRAMMING
Figure 2: UPS configuration in /usr/local/
ups/etc/ups.conf.
Figure 3: NUT daemon configuration in /usr/
local/ups/etc/upsd.conf.
goes well, the script prints UPS OK - OL
and returns an exit code of 0. If the UPS
is on battery power, the script returns
UPS CRITICAL - OB and exits with exit
code 2 to tell Nagios about the problem.
And … Action!
Nagios follows the notion of “soft” and
“hard” status changes. If a check indi-
cates a critical condition for the first time
but the parameter max_check_attempts
is set to 3, Nagios makes a note of the
problem but sets the status to SOFT first.
When subsequent checks retry_check_
interval seconds later also fail and max_
check_attempts is finally reached, the
status is set to HARD and the notifica-
tion mechanisms kick in. It’s possible
to configure emails to be sent out to
24
25 if ($data eq "OB") {
26 $status = "critical";
27 }
28
29 print "UPS ", uc($status),
30 " - $data\n";
31
32 exit $ncli->exitvalue(
33 $status);
ISSUE 80 JULY 2007 75
PROGRAMMING Perl: Uninterruptible Power Supply
provide a rude awakening to the system
administrator on call.
Nagios also allows you to initiate ac-
tions when status changes occur. This
way, scripts can try to fix the problem,
and if the solution is as simple as restart-
ing a web server, it’s probably a good
idea to do that instead of bothering a
system administrator. In the case of a
UPS at home running out of battery
power, we just want the Linux system to
shut itself down properly to avoid a hard
landing. The event handler in Listing 2,
powerdown, does exactly that.
Figure 4: Nagios configuration for the UPS
check and its powerdown event handler.
01 #!/usr/bin/perl -w
02 #############################
03 # powerdown event handler
04 # Mike Schilli, 2007
05 #############################
06 use strict;
07 use Sysadm::Install qw(:all);
08 use Log::Log4perl qw(:easy);
09
10 Log::Log4perl->easy_init({
11 file =>
12 ">>/tmp/powerdown.log",
13 level => $DEBUG
14 });
76 ISSUE 80 JULY 2007
Figure 5: Nagios shows that the UPS is running on battery power.
But be careful, Nagios calls the script out having to type a password. Both
defined with the event handler directive scripts, check_myups and powerdown,
with every status change: first, when the have to be installed in the Nagios plugin
status changes from OK to CRITICAL/ directory, /usr/local/nagios/libexec.
SOFT, then when it changes from CRITI- When the changes to the Nagios config-
CAL/SOFT to CRITICAL/HARD, and fi- uration have been made, Nagios needs
nally after it recovers from CRITICAL to be restarted.
HARD to OK. Now you'll be ready when the next
The powerdown script, which gets power outage comes! ■
the status information that is passed in,
makes sure that a poweroff of the ma- INFO
chine only happens in case a critical
[1] Network UPS Tools (NUT):
hard state is encountered and ignores
http://www.networkupstools.org/
all other requests.
[2] “The Watcher” by Michael Schilli.
Per the configuration in Figure 4, Nag-
Linux Magazine, June 2006:
ios passes in the two variables SERVIC-
http://www.linux-magazine.com/
ESTATE (ok/critical) and SERVICESTA- issue/67/Perl_Nagios_Plugins.pdf
TETYPE (soft/hard) so powerdown can
[3] Turnbull, James. Pro Nagios 2.0.
make an informed decision.
Apress, 2006.
If I’m out of battery power, the event
[4] Listings for this article:
handler will want to run the Linux pow-
http://www.linux-magazine.com/
eroff script, but only root can do that. To
Magazine/Downloads/80
make sure that the nagios user running
the Nagios application has permission to
do that, the following entry is added to Michael Schilli works
as a Software Devel-
the sudoers file:
THE AUTHOR
oper at Yahoo!,
Sunnyvale, Califor-
# /etc/sudoers nia. He wrote “Perl
nagios ALL= NOPASSWD:U Power” for Addison-
/usr/bin/poweroff Wesley and can be
contacted at mschilli@perlmeister.
com. His homepage is at
With this setting, the nagios user can
http://perlmeister.com.
run sudo /usr/bin/poweroff as root with-
Listing 2: powerdown
15 29 exit 0;
16 my ($state, $softhard) = 30 }
17 @ARGV; 31
18 32 if ($softhard eq "SOFT") {
19 LOGDIE 33 DEBUG "Ignoring soft mode";
20 "usage: $0 state SOFT|HARD" 34 exit 0;
21 if !$softhard 35 }
22 or $softhard !~ /SOFT|HARD/; 36
23 37 # Shut PC off
24 DEBUG 38 INFO "Shutting down";
25 "Called $0 $state $softhard"; 39 tap("sudo",
26 40 "/usr/bin/poweroff");
27 if ($state eq "OK") {
28 DEBUG "Ignoring OK";
W W W. L I N U X - M A G A Z I N E . C O M