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.

cpanm UPS::Nut

perl -MCPAN -e shell
install UPS::Nut