NAME
   AnyEvent::Porttracker - Porttracker/PortIQ API client interface.

SYNOPSIS
      use AnyEvent::Porttracker;

      my $api = new AnyEvent::Porttracker
         host => "10.0.0.1",
         user => "admin",
         pass => "31331",
         tls  => 1,
      ;

      # Example 1
      # a simple request: ping the server synchronously

      my ($timestamp, $pid) = $api->req_sync ("ping");

      # Example 2
      # find all realms, start a discovery on all of them
      # and wait until all discovery processes have finished
      # but execute individual discoveries in parallel,
      # asynchronously

      my $cv = AE::cv;

      $cv->begin;
      # find all realms
      $api->req (realm_info => ["gid", "name"], sub {
         my ($api, @realms) = @_;

         # start discovery on all realms
         for my $realm (@realms) {
            my ($gid, $name) = @$realm;

            $cv->begin;
            $api->req (realm_discover => $gid, sub {
               warn "discovery for realm '$name' finished\n";
               $cv->end;
            });
         }

         $cv->end;
      });

      $cv->recv;

      # Example 3
      # subscribe to realm_poll_stop events and report each occurance

      $api->req (subscribe => "realm_poll_stop", sub {});
      $api->on (realm_poll_stop_event => sub {
         my ($api, $gid) = @_;
         warn "this just in: poll for realm <$gid> finished.\n";
      });

      AE::cv->recv; # wait forever

DESCRIPTION
   Porttracker (<http://www.porttracker.com/>) is a product that (among
   other things) scans switches and routers in a network and gives a
   coherent view of which end devices are connected to which switch ports
   on which switches and routers. It also offers a JSON-based client API,
   for which this module is an implementation.

   In addition to Porttracker, the PortIQ product is also supported, as it
   uses the same protocol.

   If you do not have access to either a Porttracker or PortIQ box then
   this module will be of little value to you.

   This module is an AnyEvent user, you need to make sure that you use and
   run a supported event loop.

   To quickly understand how this module works you should read how to
   construct a new connection object and then read about the event/callback
   system.

   The actual low-level protocol and, more importantly, the existing
   requests and responses, are documented in the official Porttracker API
   documentation (a copy of which is included in this module as
   AnyEvent::Porttracker::protocol.

THE AnyEvent::Porttracker CLASS
   The AnyEvent::Porttracker class represents a single connection.

   $api = new AnyEvent::Porttracker [key => value...]
       Creates a new porttracker API connection object and tries to connect
       to the specified host (see below). After the connection has been
       established, the TLS handshake (if requested) will take place,
       followed by a login attempt using either the "none",
       "login_cram_md6" or "login" methods, in this order of preference
       (typically, "login_cram_md6" is used, which shields against some
       man-in-the-middle attacks and avoids transferring the password).

       It is permissible to send requests immediately after creating the
       object - they will be queued until after successful login.

       Possible key-value pairs are:

       host => $hostname [MANDATORY]
           The hostname or IP address of the Porttracker box.

       port => $service
           The service (port) to use (default: "porttracker=55").

       user => $string, pass => $string
           These are the username and password to use when authentication
           is required (which it is in almost all cases, so these keys are
           normally mandatory).

       tls => $bool
           Enables or disables TLS (default: disables). When enabled, then
           the connection will try to handshake a TLS connection before
           logging in. If unsuccessful a fatal error will be raised.

           Since most Porttracker/PortIQ boxes will not have a
           sensible/verifiable certificate, no attempt at verifying it will
           be done (which means man-in-the-middle-attacks will be trivial).
           If you want some form of verification you need to provide your
           own "tls_ctx" object with "verify => 1, verify_peername => [1,
           1, 1]" or whatever verification mode you wish to use.

       tls_ctx => $tls_ctx
           The AnyEvent::TLS object to use. See "tls", above.

       on_XYZ => $coderef
           You can specify event callbacks either by sub-classing and
           overriding the respective methods or by specifying code-refs as
           key-value pairs when constructing the object. You add or remove
           event handlers at any time with the "event" method.

   $api->req ($type => @args, $callback->($api, @reply))
       Sends a generic request of type $type to the server. When the server
       responds, the API object and the response arguments (without the
       success status) are passed to the callback, which is the last
       argument to this method.

       If the request fails, then a fatal error will be raised. If you want
       to handle failures gracefully, you need to use "->req_failok"
       instead.

       The available requests are documented in the Porttracker API
       documentation (a copy of which is included in this module as
       AnyEvent::Porttracker::protocol.

       It is permissible to call this (or any other request function) at
       any time, even before the connection has been established - the API
       object always waits until after login before it actually sends the
       requests, and queues them until then.

       Example: ping the porttracker server.

          $api->req ("ping", sub {
             my ($api, $ok, $timestamp, $pid) = @_;
             ...
          });

       Example: determine the product ID.

          $api->req (product_id => sub {
             my ($api, $ok, $branding, $product_id) = @_;
             ...
          });

       Example: set a new license.

          $api->req (set_license => $LICENSE_STRING, sub {
             my ($api, $ok) = @_;

             $ok or die "failed to set license";
          });

   @res = $api->req_sync ($type => @args)
       Similar to "->req", but waits for the results of the request and on
       success, returns the values instead (without the success flag, and
       only the first value in scalar context). On failure, the method will
       "croak" with the error message.

   $api->req_failok ($type => @args, $callback->($api, $success, @reply))
       Just like "->req", with two differences: first, a failure will not
       raise an error, second, the initial status reply which indicates
       success or failure is not removed before calling the callback.

   $api->on (XYZ => $callback)
       Overwrites any currently registered handler for "on_XYZ" or installs
       a new one. Or, when $callback is undef, unregisters any
       currently-registered handler.

       Example: replace/set the handler for "on_discover_stop_event".

          $api->on (discover_stop_event => sub {
             my ($api, $gid) = @_;
             ...
          });

EVENTS/CALLBACKS
   AnyEvent::Porttracker connections are fully event-driven, and naturally
   there are a number of events that can occur. All these events have a
   name starting with "on_" (example: "on_login_failure").

   Programs can catch these events in two ways: either by providing
   constructor arguments with the event name as key and a code-ref as
   value:

      my $api = new AnyEvent::Porttracker
         host => ...,
         user => ..., pass => ...,
         on_error => sub {
            my ($api, $msg) = @_;
            warn $msg;
            exit 1;
         },
      ;

   Or by sub-classing "AnyEvent::Porttracker" and overriding methods of the
   same name:

      package MyClass;

      use base AnyEvent::Porttracker;

      sub on_error {
         my ($api, $msg) = @_;
         warn $msg;
         exit 1;
      }

   Event callbacks are not expected to return anything and are always
   passed the API object as first argument. Some might have default
   implementations (for example, "on_error"), others are ignored unless
   overriden.

   Description of individual events follow:

   on_error $api, $msg
       Is called for every (fatal) error, including "error" notifies. The
       default prints the message and destroys the object, so it is highly
       advisable to override this event.

   on_login $api, $method
       Called after a successful login, after which commands can be send.
       It is permissible to send commands before a successful login: those
       will be queued and sent just before this event is invoked. $method
       is the auth method that was used.

   on_login_failure $api, $msg
       Called when all login attempts have failed - the default raises a
       fatal error with the error message from the server.

   on_hello_notify $api, $version, $authtypes, $nonce
       This protocol notification is used internally by
       AnyEvent::Porttracker - you can override it, but the module will
       most likely not work.

   on_info_notify $api, $msg
       Called for informational messages from the server - the default
       implementation calls "warn" but otherwise ignores this notification.

   on_error_notify $api, $msg
       Called for fatal errors from the server - the default implementation
       calls "warn" and destroys the API object.

   on_start_tls_notify $api
       Called when the server wants to start TLS negotiation. This is used
       internally and - while it is possible to override it - should not be
       overridden.

   on_event_notify $api, $eventname, @args
       Called when the server broadcasts an event the API object is
       subscribed to. The default implementation (which should not be
       overridden) simply re-issues an "on_eventname_event" event with the
       @args.

   on_XYZ_notify $api, ...
       In general, any protocol notification will result in an event of the
       form "on_NOTIFICATION_notify".

   on_XYZ_event $api, ...
       Called when the server broadcasts the named (XYZ) event.

SEE ALSO
   AnyEvent, <http://www.porttracker.com/>,
   <http://www.infoblox.com/en/products/portiq.html>.

AUTHOR
    Marc Lehmann <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.