#!/usr/bin/perl -w
#==============================================================================
# description:
#------------------------------------------------------------------------------
# Perl script to get informations about the current UPS status, the comparison
# between the rating and current status and the manufacturer using an
# Hardware::UPS::Perl driver either via a running UPS agent or directly on a
# serial device.
#==============================================================================
#==============================================================================
# embedded pod documentation:
#------------------------------------------------------------------------------
=head1 NAME
upsstat - gets informations about the UPS using an Hardware::UPS::Perl
driver indirectly via TCP or directly on a serial device
=head1 SYNOPSIS
B<upsstat>
S<[ B<-h>, B<--help> ]> S<[ B<-M>, B<--man> ]> S<[ B<-V>, B<--version> ]>
S<[ B<-D>, B<--driver> I<driver> ]>
S<[ B<-d>, B<--debug-level> [I<debuglevel>] ]>
S<[ B<-r>, B<--remote> [I<HOST:[PORT]> ]>
S<[ B<-a>, B<--all> ]>
S<[ B<-c>, B<--comparison> ]>
S<[ B<-i>, B<--info> ]>
S<[ B<-s>, B<--status> ]>
[I<device-name>]
=head1 DESCRIPTION
B<upsstat> gets informations about an UPS itself, its current status and
the comparison between the rating and current data using a driver specified on
the command line and prints them to F<STDOUT>. There are to ways of operating:
On the one hand, the UPS can reside on a local serial device specified by the
optional F<device-name> parameter. If the parameter is omitted, F</dev/ttyS0>,
i.e. the COM1 port, is used per default unless overriden by the environment
variable F<UPS_DEVICE>.
On the other hand, the UPS informations can be retrieved via TCP/IP, if there
is an UPS agent running at a remote host specified by the F<--remote> option.
=head1 OPTIONS
=over 4
=item B<-h>, B<--help>
Displays a short usage help message and exits without errors.
=item B<-M>, B<--man>
Displays the embedded pod documentation of B<upswatch> (this screen) using
B<pod2man>, B<groff> and B<less> as pager; it exits without errors.
=item B<-V>, B<--version>
Displays version information and exits without errors.
=item B<-D>, B<--driver> I<driver>
Sets the UPS driver I<driver> to use. I<driver> is a case-insensitive string.
If not specified, the default driver "Megatec" is used.
=item B<-d>, B<--debug-level> [I<debuglevel>]
Sets the integer debug level I<debuglevel>. If the debug level is not
specified, a default of 1 is assumed. A higher debug level will increase the
verbosity. The maximum is 5.
=item B<-r>, B<--remote> [I<HOST[:PORT]>]
Switches to the remote operation modus, i.e. the UPS is watched via TCP/IP
using a remotely running UPS agent. The remote site is specified by the
F<HOST> and optionally the TCP port F<PORT> separated by ':'. If not
specified, the local host's default FQDN will be used together with default
TCP port F<9050>.
=item B<-a>, B<--all>
Gets all UPS informations available.
=item B<-c>, B<--comparison>
Gets the comparison between the rating info (firmware data) and the current
data of the UPS.
=item B<-i>, B<--info>
Gets the UPS informations, i.e. the manufacturer, model and the firmware
version.
=item B<-s>, B<--status>
Gets the current UPS status informations; this is the default.
=back
=head1 EXAMPLES
=over 4
=item B<upsstat>
Retrieves the status of an UPS on COM1.
=item B<upsstat> I</dev/ttyS1>
Retrieves the status of an UPS on COM2.
=item B<upsstat> B<-r> I<192.168.1.2:7030>
Connects to an UPS located at host F<192.168.1.2> via an UPS agent listening
at TCP port F<7030> at this host and retrieves its status.
=back
=head1 SEE ALSO
groff(1),
less(1),
pod2man(1),
upsadm(1)
upsagent(1),
upswatch(1),
Getopt::Long(3pm),
Time::HiRes(3pm),
Hardware::UPS::Perl::Connection(3pm),
Hardware::UPS::Perl::Connection::Net(3pm),
Hardware::UPS::Perl::Connection::Serial(3pm),
Hardware::UPS::Perl::Constants(3pm),
Hardware::UPS::Perl::Driver(3pm),
Hardware::UPS::Perl::Driver::Megatec(3pm),
Hardware::UPS::Perl::General(3pm),
Hardware::UPS::Perl::Logging(3pm),
Hardware::UPS::Perl::PID(3pm),
Hardware::UPS::Perl::Utils(3pm)
=head1 AUTHOR
Christian Reile, Christian.Reile@t-online.de
=cut
#==============================================================================
# Entries for revision control:
#------------------------------------------------------------------------------
# Revision : $Revision: 1.3 $
# Author : $Author: creile $
# Last Modified On: $Date: 2007/04/17 19:53:34 $
# Status : $State: Exp $
#------------------------------------------------------------------------------
# Modifications :
#------------------------------------------------------------------------------
#
# $Log: upsstat.pl,v $
# Revision 1.3 2007/04/17 19:53:34 creile
# unnecessary comments removed.
#
# Revision 1.2 2007/04/14 09:37:26 creile
# documentation update.
#
# Revision 1.1 2007/04/07 14:53:06 creile
# initial revision.
#
#
#==============================================================================
#==============================================================================
# packages required:
#------------------------------------------------------------------------------
#
# Getopt::Long - processing options
# strict - restricting unsafe constructs
#
# Hardware::UPS::Perl::Constants - importing Hardware::UPS::Perl constants
# Hardware::UPS::Perl::General - importing Hardware::UPS::Perl variables
# and functions for scripts
# Hardware::UPS::Perl::Logging - importing Hardware::UPS::Perl methods
# dealing with log files
#
#==============================================================================
use Getopt::Long;
use strict;
use Hardware::UPS::Perl::Constants qw(
UPSFQDN
UPSPORT
UPSSCRIPT
UPSTCPPORT
);
use Hardware::UPS::Perl::General;
use Hardware::UPS::Perl::Logging;
#==============================================================================
# defining global variables:
#------------------------------------------------------------------------------
#
# $DebugLevel - the debug level
# $Driver - the actual driver to use
# $Host - the host the UPS resides
# $Logger - the logger
# $Port - the actual serial device the UPS is located on
# $GetCompareFlag - flag to get the comparison between the rating
# info and the current UPS status
# $GetInfoFlag - flag to get the the UPS informations
# $GetStatusFlag - flag to get the the current UPS status
#
#==============================================================================
use vars qw(
$DebugLevel
$Driver
$Host
$Logger
$Port
$GetCompareFlag
$GetInfoFlag
$GetStatusFlag
);
#==============================================================================
# defining subroutines:
#==============================================================================
sub Init {
# subroutine for initializing the working environment
# initializing the working environment
InitWE();
# revision number
use constant REVISION_VERSION => sprintf(
"%d.%02d", q$Revision: 1.3 $ =~ /(\d+)\.(\d+)/
);
# revison date
use constant REVISION_DATE => sprintf(
"%d/%02d/%02d", q$Date: 2007/04/17 19:53:34 $ =~ /(\d+)\/(\d+)\/(\d+)/
);
# the default driver
use constant DRIVER => "Megatec";
} # end of subroutine "Init"
sub GetParameters {
# subroutine for getting and checking options
# hidden local variables
my $debugLevel; # switch to specify the debug level
my $driver; # switch to specify the driver to load
my $host; # switch to specify the host the UPS resides
my $allFlag; # switch to get all UPS informations available
my $compareFlag; # switch to get the rating info and current UPS data
my $infoFlag; # switch to get UPS info
my $statusFlag; # switch to get the UPS status
my $help; # switch for displaying usage help
my $manpage; # switch for displaying man page
my $version; # switch for displaying version information
my $return; # returning error
# configuring subroutine `GetOptions': case sensitivity
&Getopt::Long::config("no_ignore_case");
# getting options
$return = GetOptions(
"all|a" => \$allFlag ,
"compare|c" => \$compareFlag,
"debug-level|d:i" => \$debugLevel ,
"info|i" => \$infoFlag ,
"status|s" => \$statusFlag ,
"driver|D=s" => \$driver ,
"remote|r:s" => \$host ,
"help|h" => \$help ,
"man|M" => \$manpage ,
"version|V" => \$version ,
);
# checking all options
Usage(1) if ( ! $return );
# displaying usage help and exit without errors
Usage(0) if ( $help );
# displaying man page and exit without errors
ManPage() if ( $manpage );
# displaying version information and exit without errors
if ( $version ) {
Version(REVISION_VERSION, REVISION_DATE, "returns the UPS status");
}
# checking individual options
#
# setting the debug level
if ( defined($debugLevel) ) {
$DebugLevel = $debugLevel ? $debugLevel : 1;
}
else {
$DebugLevel = 0;
}
# the driver to use
$Driver = $driver ? $driver : DRIVER;
# tasks
$GetCompareFlag = 0;
$GetInfoFlag = 0;
$GetStatusFlag = 1;
if ($allFlag) {
$GetCompareFlag = 1;
$GetInfoFlag = 1;
$GetStatusFlag = 1;
}
else {
if ($compareFlag) {
$GetCompareFlag = 1;
$GetStatusFlag = 0;
}
if ($infoFlag) {
$GetInfoFlag = 1;
$GetStatusFlag = 0;
}
if ($statusFlag) {
$GetStatusFlag = 1;
}
}
# setting the operation modus
if (defined $host) {
# remote watch
$Host = $host ? $host : UPSFQDN;
if ($Host =~ /:/) {
$Host = $`;
$Port = $';
}
else {
$Port = UPSTCPPORT;
}
}
else {
# local watch
$Host = q{};
# setting the serial port
$Port = $ARGV[0] ? $ARGV[0] : UPSPORT;
}
# setting the logger
$Logger = Hardware::UPS::Perl::Logging->new({
File => \*STDOUT,
});
if (!defined $Logger) {
Error("creating logger failed -- $UPSERROR");
}
} # end of subroutine "GetParameters"
sub Usage {
# subroutine for displaying a short usage help and exiting, if
# $exitStatus >= 0;
#
# parameters: $exitStatus (input) - status on exit
# input as hidden local variable
my $exitStatus = shift;
# displaying short usage help on STDOUT
print <<EOF;
Usage: ${\(UPSSCRIPT)} [options] [device-name]
Argument:
device-name the (optional) serial device name
[${\(UPSPORT)}]
Options:
-h, --help Displays this help message.
-M, --man Displays the man page of "${\(UPSSCRIPT)}".
-V, --version Displays version information.
-D, --driver driver sets the driver to use [driver=${\(DRIVER)}].
-d, --debug-level [debuglevel] sets the optional debug level
debuglevel [debuglevel=1].
-r, --remote [HOST[:PORT]] connects to (remote) UPS agent running
at host HOST and TCP port PORT
[HOST=${\(UPSFQDN)}, PORT=${\(UPSTCPPORT)}].
-a, --all gets all UPS informations available.
-c, --comparison gets the comparison between the UPS rating
info and the current UPS status.
-i, --info gets the UPS informations about the
manufacturer, the model and the firmware
version.
-s, --status gets the current UPS status; this is the
default.
EOF
# exiting, if $exitStatus >= 0
exit $exitStatus;
} # end of subroutine "Usage"
#==============================================================================
# start of main body:
#==============================================================================
# hidden local variables
my $connectOptions; # the connection options
my $ups; # the UPS object
# initializing of working environment
Init();
# getting options
GetParameters();
# connecting to UPS
if ($Host) {
# remotely via TCP
$connectOptions = {
Host => $Host ,
TCPPort => $Port ,
DebugLevel => $DebugLevel,
Driver => $Driver ,
Logger => $Logger ,
};
}
else {
# locally via a serial port
$connectOptions = {
SerialPort => $Port ,
DebugLevel => $DebugLevel,
Driver => $Driver ,
Logger => $Logger ,
};
}
$ups = ConnectUPS($connectOptions);
# reading UPS rating info, the current UPS status and printing the comparison
# to STDOUT
if ($GetCompareFlag) {
if ($ups->readStatus()) {
if ($ups->readRatingInfo()) {
if (!$ups->printData()) {
Warning(
"printing UPS data failed -- ".$ups->getErrorMessage()
);
}
}
else {
Warning(
"getting UPS rating info failed -- ".$ups->getErrorMessage()
);
}
}
else {
Warning("getting UPS status failed -- ".$ups->getErrorMessage());
$GetStatusFlag = 0;
}
}
# reading UPS information and printing it to STDOUT
if ($GetInfoFlag) {
if ($ups->readUPSInfo()) {
if (!$ups->printUPSinfo()) {
Warning(
"printing UPS information failed -- ".$ups->getErrorMessage()
);
}
}
else {
Warning("getting UPS information failed -- ".$ups->getErrorMessage());
}
}
# reading UPS Status and printing it to STDOUT
if ($GetStatusFlag) {
if (!$GetCompareFlag) {
if (!$ups->readStatus()) {
Warning("getting UPS status failed -- ".$ups->getErrorMessage());
$GetStatusFlag = 0;
}
}
if ($GetStatusFlag) {
if (!$ups->printStatus()) {
Warning("printing UPS status failed -- ".$ups->getErrorMessage());
}
}
}
# exiting
exit 0;