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 version 1.5 and above (https://www.networkupstools.org/). Note that it only talks to upsd for you in a Perl-ish way. It doesn't monitor the UPS continously.

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.

Important notice
This version of UPS::Nut is not compatible with version 0.04. It is totally rewritten in order to talk the new protocol of NUT 1.5+. You should not use this module as a drop-in replacement of previous version from 2002. Allmost all method has changed slightly.

Methods
Unlike in version 0.04 no methods return list values but a single reference or undef.

  Methods for querying UPS status

Getvar($varname)
    returns value of the specified variable. Returns undef if variable unsupported. Old method named Request() is also supported for compatibility.

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. Same as GetVar('battery.charge').

LoadPercent($context)
    returns percentage of the load on the UPS. Returns undef if load percentage is unavailable. $context is a selector of 3 phase systems. Possibled values are 1, 2, 3, 'L1', 'L2', 'L3'. It should be omitted in case of single phase UPS.

LineVoltage($context)
    returns input line (e.g. the outlet) voltage. Returns undef if line voltage is unavailable. $context is a selector of 3 phase systems. Possibled values are 1, 2, 3, 'L1', 'L2', 'L3'. It should be omitted in case of single phase UPS.

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. Same as GetVar('ups.status').

Temperature()
    returns UPS internal temperature. Returns undef if internal temperature unavailable. Same as GetVar('battery.temperature').

  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.

Login($username, $password)
    Notify upsd that client is drawing power from the given UPS. It is automatically done if new() is called with USERNAME, PASSWORD and LOGIN parameters.

Logout()
    Notify upsd that client is released UPS. (E.g. it is shutting down.) It is automatically done if connection closed.

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.

    TODO: API change pending to replace MASTER with PRIMARY (and backwards-compatible alias handling)

ListVar($variable, ...)
    This is an implementation of "LIST VAR" command. Returns a hash reference to selected variable names and values supported by the UPS. If no variables given it returns all. Returns undef if "LIST VAR" failed. (Note: This method significally differs from the old ListVars() and ListRequest().)

ListRW()
    Similar to ListVar() but cares only with read/writeable variables.

ListEnum($variable)
    Returns a reference to the list of all possible values of $variable. List is empty if $variable is not an ENUM type. (See GetType().) Returns undef if error occurred.

ListCmd()
    Returns a reference to the list of all instant commands supported by the UPS. Returns undef if these are unavailable. This method replaces the old ListInstCmds().

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.

GetDesc($variable)
    Returns textual description of $variable or undef in case of error. Old method named VarDesc() is also supported for compatibility.

GetCmdDesc($command)
    This is like GetDesc() above but applies to the instant commands. Old method named InstCmdDesc() is also supported for compatibility.

GetType($variable)
    Returns a string UNKNOWN or constructed one or more words of RW, ENUM and STRING:n (where n is a number). (Seems to be not working perfectly at upsd 2.2.) Old method named VarType() is also supported for compatibility.

ListUPS()
    Returns a reference to hash of all available UPS names and descriptions.

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
  Original version made by Kit Peters
  perl@clownswilleatyou.com
  http://www.awod.com/staff/kpeters/perl/

  Rewritten by Gabor Kiss <kissg@ssg.ki.iif.hu>.

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.