UPS::Nut(3)

NAME
Nut - a module to talk to a UPS via NUT (Network UPS Tools) upsd

SYNOPSIS
 use UPS::Nut;

 $ups = new UPS::Nut( NAME => "myups",
                      HOST => "somemachine.somewhere.com",
                      PORT => "3493",
                      USERNAME => "upsuser",
                      PASSWORD => "upspasswd",
                      TIMEOUT => 30,
                      DEBUG => 1,
                      DEBUGOUT => "/some/file/somewhere",
                    );
 if ($ups->Status() =~ /OB/) {
    print "Oh, no!  Power failure!\n";
 }

 tie %other_ups, 'UPS::Nut',
     NAME => "myups",
     HOST => "somemachine.somewhere.com",
     ... # same options as new();
 ;

 print $other_ups{MFR}, " ", $other_ups{MODEL}, "\n";

DESCRIPTION
This is an object-oriented (whoo!) interface between Perl and upsd from the Network UPS Tools package (http://www.exploits.org/nut/). Note that it only talks to upsd for you in a Perl-ish way. It doesn't continually monitor the UPS.

CONSTRUCTOR
Shown with defaults: new UPS::Nut( NAME => "default",
                        HOST => "localhost",
                        PORT => "3493",
                        USERNAME => "",
                        PASSWORD => "",
                        DEBUG => 0,
                        DEBUGOUT => "",
                        ); * NAME is the name of the UPS to monitor, as specified in ups.conf * HOST is the host running upsd * PORT is the port that upsd is running on * USERNAME and PASSWORD are those that you use to login to upsd. This
  gives you the right to do certain things, as specified in upsd.conf. * DEBUG turns on debugging output, set to 1 or 0 * DEBUGOUT is de thing you do when de s*** hits the fan. Actually, it's
  the filename where you want debugging output to go. If it's not
  specified, debugging output comes to standard output.

Methods

  Methods for querying UPS status
Request(varname)
  returns value of the specified variable. Returns undef if variable
  unsupported.

Set(varname, value)
  sets the value of the specified variable. Returns undef if variable
  unsupported, or if variable cannot be set for some other reason. See
  Authenticate() if you wish to use this function.

BattPercent()
  returns percentage of battery left. Returns undef if we can't get
  battery percentage for some reason.

LoadPercent()
  returns percentage of the load on the UPS. Returns undef if load
  percentage is unavailable.

LineVoltage()
  returns input line (e.g. the outlet) voltage. Returns undef if line
  voltage is unavailable.

Status()
  returns UPS status, one of OL or OB. OL or OB may be followed by LB,
  which signifies low battery state. OL or OB may also be followed by
  FSD, which denotes that the forced shutdown state
  ( see UPS::Nut->FSD() ) has been set on upsd. Returns undef if status
  unavailable.

Temperature()
  returns UPS internal temperature. Returns undef if internal temperature
  unavailable.

  Other methods
  These all operate on the UPS specified in the NAME argument to the
  constructor.

Authenticate( username, password )
  With NUT certain operations are only available if the user has the
  privilege. The program has to authenticate with one of the accounts
  defined in upsd.conf.

Master()
  Use this to find out whether or not we have MASTER privileges for this
  UPS. Returns 1 if we have MASTER privileges, returns 0 otherwise.

ListVars()
  Returns a list of all read-only variables supported by the UPS. Returns
  undef if these are unavailable.

ListRW()
  Returns a list of all read/writeable variables supported by the UPS.
  Returns undef if these are unavailable.

ListInstCmds()
  Returns a list of all instant commands supported by the UPS. Returns
  undef if these are unavailable.

InstCmd (command)
  Send an instant command to the UPS. Returns 1 on success. Returns
  undef if the command can't be completed.

FSD()
  Set the FSD (forced shutdown) flag for the UPS. This means that we're
  planning on shutting down the UPS very soon, so the attached load should
  be shut down as well. Returns 1 on success, returns undef on failure.
  This cannot be unset, so don't set it unless you mean it.

Error()
  why did the previous operation fail? The answer is here. It will
  return a concise, well-written, and brilliantly insightful few words as
  to why whatever you just did went bang.

AUTOLOAD
The "instant commands" are available as methods of the UPS object. They are AUTOLOADed when called. For example, if the instant command is FPTEST, then it can be called by $ups->FPTEST.

TIE Interface
  If you wish to simply query or set values, you can tie a hash value to
  UPS::Nut and pass as extra options what you need to connect to the host.
  If you need to exercise an occasional command, you may find the return
  value of 'tie' useful, as in:

  my %ups;
  my $ups_obj = tie %ups, 'UPS::Nut', HOSTNAME=>"firewall";

  print $ups{UPSIDENT}, "\n";

  $ups_obj->Authenticate( "user", "pass" );

  $ups{UPSIDENT} = "MyUPS";

AUTHOR
  Kit Peters
  perl@clownswilleatyou.com
  http://www.awod.com/staff/kpeters/perl/

CREDITS
Developed with the kind support of A World Of Difference, Inc. <http://www.awod.com/>

Many thanks to Ryan Jessen <rjessen@cyberpowersystems.com> at CyberPower Systems for much-needed assistance.

Thanks to Wayne Wylupski <wayne@connact.com> for the code to make accessor methods for all supported vars.

LICENSE
This module is distributed under the same license as Perl itself.