AnyEvent-Porttracker
view release on metacpan or search on metacpan
Porttracker.pm view on Meta::CPAN
# 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
=head1 DESCRIPTION
Porttracker (L<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
Porttracker.pm view on Meta::CPAN
=item $api->on (XYZ => $callback)
Overwrites any currently registered handler for C<on_XYZ> or
installs a new one. Or, when C<$callback> is undef, unregisters any
currently-registered handler.
Example: replace/set the handler for C<on_discover_stop_event>.
$api->on (discover_stop_event => sub {
my ($api, $gid) = @_;
...
});
=cut
sub on {
my $self = shift;
while (@_) {
my ($event, $cb) = splice @_, 0, 2;
Porttracker/protocol.pod view on Meta::CPAN
< [null, "event", <type>, <args...>]
This notice is sent each time an event occurs that the session is
subscribed to (see C<subscribe> and C<unsubscribe> commands).
Currently known events are:
=over 4
=item realm_discover_start realm-gid
Called with the GID of the realm that has just started a discovery process.
=item realm_discover_stop realm-gid
Called with the GID of the realm that has just finished a discovery process.
=item realm_poll_start realm-gid
Called with the GID of the realm that has just started a poll process.
=item realm_poll_stop realm-gid
Called with the GID of the realm that has just finished a poll process.
=back
=back
=head2 REQUESTS AND RESPONSES
Porttracker/protocol.pod view on Meta::CPAN
Setting the license requires admin privileges.
=item "realm_info" - information about realms
> [<id>, "realm_info", [<fields...>], [<realms...>]]
< [<id>, 1, [ [<fields...>]... ]]
Example:
> [1,"realm_info",["gid","description","polling","name","seeds"]]
< [1,1,["5000015442","","0","Realm Name","192.168.33.19"]]
> [1, "realm_info", ["gid", "discovery_result", "poll_result", "sync_result"]]
< [1,1,["64424509927",{"infrastructure":13},{"poll":{"infrastructure":13,
"ports":"339","end":"79"}},{"sync":{"qsync":null,"bsync":"Success"}}]]
Requests information about the given realms (or all realms if specified as
C<null>). The following fields can be requested, and their contents will be
returned in the order specified in the C<fields> array:
=over 4
=item gid - the gid (id value) identifying the realm
=item name - the user-specified name of the realm
=item description - the user-specified description for this realm
=item last_discover - timestamp of last discover run
=item last_poll - timestamp of last poll run
=item last_sync - timestamp of last sync run
=item polling - 0 (not polling) or 1 (currently polling)
=item syncing - 0 (not syncing) or 1 (currently syncing)
=item seeds - the seed list (whitespace-separated list of seed devices)
=item pollers - a list of poller-gids of pollers attached to the realm
=item discovery_result - a hash with key as infrastructure and value as number of devices discovered
=item poll_result - a hash with keys infrastructure, ports and end and values as their counts
=item sync_result - a hash with keys qsync and bsync and values as their results
=item ageing_interval - ping sweep interval for this realm.
=back
=item "realm_info_modify" - edits the given realm
> [<id>, "realm_info_modify", <realm-gid>, {<prop>:<value>,...}]
< [<id>, 1]
A property hash followed by a realm gid. Keys of the hash are name,
description, discovery_poller and ageing_interval.
Example:
> [1, "realm_info_modify", "38952865423", {"name":"default-1"}]
< [1, 1]
=item "realm_modify" - adds and/or deletes realms
> [<id>, "realm_modify", [delete-ids...], [[add-realm],...]]
< [<id>, 1]
Two arrays expected as input. First array is a list of realm gids needs to be deleted.
Second array is a list of realm needs to be added. An array per realm can contain
realm name and description.
Example:
> [1, "realm_modify", ["38456782341"], [["Test Realm", "for test"]]]
< [1, 1]
=item "realm_discover" - run discovery on a given realm
> [<id>, "realm_discover", <realm-gid>]
< [<id>, 1]
=item "realm_poll" - run a poll on a given realm
> [<id>, "realm_poll", <realm-gid>]
< [<id>, 1, { <statistical data> } ]
=item "switch_poll" - run a poll on a given realm and switch ip
> [<id>, "switch_poll", <realm-gid>, <switch ip>]
< [<id>, 1, { <statistical data> } ]
=item "realm_sync" - run a sync on a given realm and plugin
> [<id>, "realm_sync", <realm-gid>, <sync module>]
< [<id>, 1]
The C<sync module> can be either bsync or qsync.
=item "realm_query" - query the database
This request executes a database query with filtering, much like the
device and switch views work in the user interface.
> [<id>, "realm_query", <realm-gid>, <type>
[<column-name>...], [<raw-column-name]>...],
{<column-name> : <filter-expression>...},
<history mask>,
{<port unused period> : <unused value>}
]
< [<id>, 1, [ [<result-data>]... ]]
The C<realm-gid> is the GID of the realm to query, as returned by
C<real_info>. The C<type> is the string C<device>, C<switch> or
C<switch_detail>, which corresponds to the device view, switch view or
switch detail view.
The first array of C<column-name>s specifies which columns should be
returned. The second array of C<raw-column-name>s works likewise, but
the values returned will be the "raw" (possibly octet-encoded) database
contents. Specifying the same column name in both array causes undefined
behaviour.
Porttracker/protocol.pod view on Meta::CPAN
> [5, "realm_query", "5100005442", "switch_detail",
["ifname"], [],
{ "switch" : 27 }]
< [5,1,[["Fa0/11"],["Fa0/21"], ... ,["Fa0/5"]]]
=item "report_info" - returns the available report list
This request returns the report list for the logged-in user.
> [<id>, "report_info"]
< [<id>, 1, [ [<gid>, <name>], ...]]
The reply will contains an array for each report. Each array will have gid
and name of the report.
Example:
> [1, "report_info"]
< [1,1,[["3865500631171148","New Report 1"]]]
=item "user_view_info" - return the available views list
This request returns the report views list for the logged-in user.
> [<id>, "user_view_info", [<field-list>], [<type-list>]]
< [<id>, 1, [ [<fields>, ...], ...]]
Valid fields are C<name> and C<gid> and valid types are C<switch>,
C<port> and C<device>. The reply will contains an array for each view.
Example:
> [1, "user_view_info", ["gid", "name"]]
< [1,1,[["107374182462","Ports:Default"],
["94489280669","Ports:Multiple Devices on Port"],
["107374182460","End Devices:Default"],
["3865500631171226","End Devices:test"],
["3865500631171236","End Devices:tns04"]]]
=item "realm_view" - query database with given view in a given realm
This request returns the database entries for the given view and the realm.
> [<id>, "realm_view", <realm-gid>, <view-gid>]
< [<id>, 1,[ [<result-data>]]]
Valid view gid should be given followed by a valid realm gid.
The reply will contain the results from database query and one array per
database row.
Example:
> [1, "realm_view", "64424509927", "107374182461"]
< [1,1,[["tnsw04.uk.internal","S","26","15","15","58","0","2009-12-08 12:17:00",
"2009-12-08 12:17:00",null],["tnsw05.uk.internal","S","26","20","20"
,"77","0","2009-12-08 12:17:00","2009-12-08 12:17:00",null]]]
=item "realm_seed_list" - return the seed list
This request returns the seed list for the given realm.
> [<id>, "realm_seed_list", <realm-gid>]
< [<id>, 1, [ [<ip>, <flags>]... ]]
The reply contains an array with all configured seed devices. Each device
is represented by an array with the IP address in textual form and a flags
bitset. The only defined bit value (not number) is C<2>, which indicates a
manually-added seed entry.
Example:
> [1, "realm_seed_list", "5100005442"]
< [1,1,[["192.168.40.11",0],["192.168.40.1",2]]]
=item "realm_seed_list_modify" - add/remove seed list entries
This request modifies the seed list for a realm.
> [<id>, "realm_seed_list_modify", <realm-gid>, [<delete-ip>...], [<add-ip>...>]]
< [<id>, 1]
The two arrays after the realm-gid specify the IP addresses (in textual
form) of seed entries to remove, followed by a list of IP addresses to be
added afterwards. Newly added IP addresses will have the manual flag set on them.
Example: set the manually-added flag on 10.0.0.5, or add it if it didn't
exist yet.
> [1, "realm_seed_list_modify", "5100005442", ["10.0.0.5"], ["10.0.0.5"]]
< [1,1]
=item "realm_snmp_credential_list" - list snmp credentials
This request returns the snmp credentials for the given realm.
> [<id>, "realm_snmp_credential_list", <realm-gid>]
< [<id>, 1, [ [<subnet>, <bits>, [ 2, [<community>...], [3, <v3 settings>] ], <flags>]... ]]
The reply contains an array with all configured snmp credentials, one per
subnet. Each snmp credential will contain the subnet address in textual
form, the leading number of significant bits in the subnet (0..32 for
IPv4, 0..128 for IPv6), an array per snmp v2 and v3 settings and a flags bitset
(bit value C<1> means it is an include, otherwise it is an exclude).
v2 array starts with bit value C<2> means it is version v2 and followed by an array
of community strings. v3 array starts with bit value C<3> means it is version v3 and
followed by v3 user name, authentication password, privacy password, authentication
Porttracker/protocol.pod view on Meta::CPAN
Example:
> [1, "realm_snmp_credential_list", "5100005442"]
< [1,1,[ ["10.1.0.0",16,[[2,["test"]], [3,"authPrivUser","authpass","privpass", null, "md5","aes"]],1] ]]
=item "realm_snmp_credential_list_modify" - modify snmp credentials
Removes and/or adds snmp credential entries.
> [<id>, "realm_snmp_credential_list_modify", <realm-gid>, [<remove-subnet>], [<add-subnet>...]]
< [<id>, 1]
The two arrays after the realm-gid specify a list of subnet addresses to
remove (only exact matches wil be removed) and a list of subnet-entries to
be added afterwards. Each entry in the <add-subnet> list follows the same
format as returned by C<realm_snmp_credentials>.
Example:
> [1, "realm_snmp_credential_list_modify", "5100005442", [ ["10.0.0.0", 8], ["11.1.1.0", 24] ],
[ ["192.168.240.0", 24, [[2, ["w0rld", "peace"]], [3, "noAuthUser"]], 1] ]]
< [1, 1]
=item "realm_device_assignment_list" - list all assignable devices for a realm
This request returns all assignable devices.
> [<id>, "realm_device_assignment", <realm-gid>]
< [<id>, 1, [ [<ip>, <poller-gid>] ]]
The reply contains an array with all assignable devices in a realm. Each
device entry will contain the device IP address in textual form, and
the gid of the poller it is assigned to, or C<null> if the device isn't
currently assigned.
Example:
> [1, "realm_device_assignment_list", "64424509927"]
< [1,1,[ ["192.168.71.21",null],["192.168.75.2",null],["1.1.1.1",64424509930],["5.5.5.5",64424509930]] ]
=item "realm_device_assign" - assign a device to a poller
Assigns or unassigns a device, or all devices.
> [<id>, "realm_device_assign", <realm-gid>]
< [<id>, 1]
> [<id>, "realm_device_assign", <realm-gid>, [<device-ip>, <poller-gid>]]
< [<id>, 1]
If only a realm-gid is specified and device and poller-gid are missing,
then all devices get auto-assigned to pollers, if possible.
Otherwise, the specified device will be assigned to the specified
C<poller-gid>, or unassigned if C<poller-gid> is C<null>.
Example:
> [1, "realm_device_assign", "64424509927"]
< [1, 1]
> [1, "realm_device_assign", "64424509927", ["1.1.1.1", null]]
< [1, 1]
> [1, "realm_device_assign", "64424509927", ["1.1.1.1", "64424509930"]]
< [1, 1]
=item "realm_advanced_settings" - list advanced settings of a given realm
This request returns all/specific properties and their values.
> [<id>, "realm_advanced_settings", <realm-gid>, [<property>,...]]
< [<id>, 1, [[<property>, <value>]...]]
If only the realm-gid is specified then all the properties and their values returned.
valid properties are
snmp_parallel_requests, snmp_retries,
snmp_timeout, skip_access_points,
smtp_user, autoassign, autoassign_manual, skip_cisco_phones, skip_mitel_phones,
block_port_macs, stp_enabled, cdp_enabled, lldp_enabled, ndp_enabled, bdp_enabled,
edp_enabled, fdp_enabled
Example:
> [1, "realm_advanced_settings", "64424509927", ["cdp_enabled"]]
< [1,1,[["cdp_enabled","1"]]]
=item "realm_advanced_settings_modify" - modify advanced settings of a given realm
This request modifies advanced settings of a given realm-gid.
> [<id>, "realm_advanced_settings_modify", <realm-gid>, [[<property>, <value>]...]]
< [<id>, 1]
> [<id>, "realm_advanced_settings_modify", <realm-gid>, [[<property>, [<delete-list>], [<add-list>]]]]
< [<id>, 1]
realm-gid followed by a array of property and value pairs. one array for each property
and value pair.
block_port_macs property expects two arrays in place of value. First array is a list of
macs needs to be deleted from port exclusion list and second array is a list of
macs needs to be added into port exclusion list. MAC addresses should be in the following
format "AA:BB:CC:DD:EE:FF".
When no array given for block_port_macs property all the macs from port exclusion list
will get deleted.
Example:
Porttracker/protocol.pod view on Meta::CPAN
["11:00:0a:0b:11:22"], ["0a:11:22:44:0e:0b"]]]]
< [1, 1]
=item "poller_info" - - information about pollers
> [<id>, "poller_info", [<fields...>], [<pollers...>]]
< [<id>, 1, [ [<fields...>]... ]]
Example:
> [1, "poller_info", ["gid", "name", "description", "hostname"]]
< [1,1,[["64424509930","localhost","localhost","127.0.0.1"]]]
Requests information about the given pollers (or all pollers if specified as
C<null>). The following fields can be requested, and their contents will be
returned in the order specified in the C<fields> array:
=over 4
=item gid - the gid (id value) identifying the poller
=item name - the user-specified name of the poller
=item description - the user-specified description for this poller
=item hostname - hostname/ip of this poller
=item dns_max_outstanding - maximum number of dns queries for this poller
=back
=item "poller_modify" - adds and/or deletes pollers
This request adds and/or deletes given pollers.
> [<id>, "poller_modify", <realm-gid>, [<delete-gid>, ...],
[[<name>, <description>, <hostname>, <secret>], ...]]
< [<id>, 1]
Two arrays followed by a realm gid. First array is a list of poller gids
needs to be deleted. Second array is a list of pollers needs to be added.
An array per poller should contain poller name, description, hostname and
secret password.
Example:
> [1, "poller_modify", "385611201213", ["98456723211"], [["test1",
"Test poller", "127.0.0.1", "test"]]]
< [1, 1]
=item "poller_info_modify - edits the given poller
This request edits the given poller with new values.
> [<id>, "poller_info_modify", <poller-gid>, {<prop>:<value>,...}]
< [<id>, 1]
A property hash followed by a poller gid. Keys expected in the hash
are name, description, hostname, secret and dns_max_outstanding.
Example:
> [1, "poller_info_modify", "6789345621", {"name":"test1",
"secret":"test123", "hostname":"localhost",
"dns_max_outstanding":"65"}]
< [1, 1]
=item "poller_subnet_list" - list subnets attached to a given poller
This request returns all subnets attached to a given poller.
> [<id>, "poller_subnet_list", <poller-gid>]
< [<id>, 1, [ [<subnet>, <bits>, <ping-limit>, <flags>]... ]]
The reply contains an array with all configured subnets. Each subnet
will contain the subnet address in textual form, the leading number of
significant bits in the subnet (0..32 for IPv4, 0..128 for IPv6), a ping
limit (in kbit/s) and a flags value (bit value C<1> indicates whether the
subnet is exclided (C<0>) or included (C<1>), bit value C<2> indicates
whether pings are enabled (C<2>) or not).
Example:
> [1, "poller_subnet_list", "64424509930"]
< [1,1,[["1.1.1.1",32,1000,1,2],["10.1.1.1",32,1000,0,0]]]
=item "poller_subnet_list_modify" - modify subnets of a poller
Removes and/or adds subnet entries.
> [<id>, "poller_subnet_list_modify", <poller-gid>, [<remove-subnet>], [<add-subnet>...]]
< [<id>, 1]
The two arrays after the poller-gid specify a list of subnet addresses to
remove (only exact matches wil be removed) and a list of subnet-entries to
be added afterwards. Each entry in the <add-subnet> list follows the same
format as returned by C<poller_subnet_list>.
Example:
> [ 1, "poller_subnet_list_modify", "64424509930",[["1.1.1.1",32,1000,1,2],
["10.1.1.1",32,1000,0,0]], [["192.168.0.0", 16, 1200, 1,2]] ]
< [1, 1]
Porttracker/protocol.pod view on Meta::CPAN
< [<id>, 1]
Example:
> [1, "security_certificate_assign", [["custom", "apache"], ["custom", "api"]]]
< [1, 1]
=item "security_authentication_method_list" - lists authentication methods and settings
This request returns all or specified properties of all or specified authentication method.
First array contains the list of properties and the second array contains the list of gids
of methods. Result array will have one array per authentication method.
Valid properties are
name gid inuse settings
> [<id>, "security_authentication_method_list", [<properties>, ...], [<method-gid>, ...]]
< [<id>, 1, [ [<value>, ...], ...]]
Example:
> [1, "security_authentication_method_list", ["name"], ["90194313753", "90194313603"]]
< [1,1,[["RADIUS"],["Active Directory (LDAPS)"]]]
=item "security_authentication_modify" - modifies given authentication methods
This request edits given authentication method.
First argument is the authentication method gid.
All new values should be mentioned in a hash.
Valid properties are
inuse server secret csecret domain ctrls certificate
bit value C<inuse> will activate/inactivate the given authentication method.
C<server> is the RADIUS server for RADIUS authentication method.
C<secret> and C<csecret> are secret password and confirm secret password for RADIUS server.
C<domain> is the domain name for LDAP and LDAPS authentication methods.
C<ctrls> is the array of delete and add lists of domain controls.
C<certificate> is the valid certificate name for LDAPS authentication method.
C<timeout> is the value in seconds to be used when communicating with Active Directory servers.
> [<id>, "security_authentication_modify", <method-gid>, {<property> : <value>,... }]
< [<id>, 1]
Example:
> [1, "security_authentication_modify", "90194313753", {"inuse" : 1, "server" : "4test"}]
< [1, 1]
> [1, "security_authentication_modify", "90194313603", {"certificate" : "custom", "domain" : "new"
"ctrls" : [ ["10.1.50.1"], ["10.1.50.2"] ]}]
< [1, 1]
=item "group_info" - lists group information
This request returns all groups or specific groups. The request returns all
fields or specific fields.
> [<id>, "group_info", [<field1>, <field2>, ...], [<group-gid>, ...]]
< [<id>, 1, [ [<value>, <value>, ...] , ...]
The reply contains an array for each group with specified field values or all.
Example:
> [1, "group_info", ["name"]]
< [1,1,[["helpme"],["Network Administrator"],["Network Operator"],["Super Admin"]]]
=item "group_modify" - adds and/or deletes groups
This request adds and/or deletes given groups.
> [<id>, "group_modify", [<delete-gid>, ...], [[<name>, <description>], ...]]
< [<id>, 1]
Two arrays expected as input. First array is a list of group gids needs to be deleted.
Second array is a list of groups needs to be added. An array per group should contain
group name and description.
Example:
> [1, "group_modify", ["9845672231"], [["test1", "Test group"]]]
< [1, 1]
=item "group_settings" - lists permissions for a given group
> [<id>, "group_settings", <group-gid>, [<role>, <role>, ...], [<realm-gid>, ...]]
< [<id>, 1, [[[<system-role>, <permission>], ...],
[[<realm-gid>, [[<realm-role>, <permission>], ...]], ...]]]
The input should have a valid group gid in textual format. Two arrays followed by group gid
are list of roles and list of realm gids. These two arrays are optional.
The result contains two arrays. First array is for system specific roles. One array per role.
Second array is for realm specific roles. One array per realm. First element of the array is
realm-gid in textual format followed by an array of realm specific roles and their permission.
Permission will be referred in bit value. bit value C<0> means NO Access, C<1> means
Read Access and C<2> means Read/Write Access.
Example:
> [1, "group_settings", "98784248728"]
< [1,1,[[["API",2],["Add Realms",2],["Advanced Settings",1],["Global Settings",2]]
,[["3865500631171652",[["Advanced Realm Settings",0],["Assign Devices",0]]]]]]
> [1, "group_settings", "98784248728", ["Add Realms", "Assign Devices"]]
< [1,1,[[["Add Realms",2]],[["3865500631171652",[["Assign Devices",0]]],
["3865500631171517",[["Assign Devices",0]]]]]]
=item "group_settings_modify" - edits group properties and permissions
> [<id>, "group_settings_modify", <group-gid>
, {"name":<group-name>, "description":<group description>}
, [[<system-role>, <permission>], ...], [[<realm-gid>,
[[<realm-role>, <permission>], ...]], ...] ]
< [<id>, 1]
The input should have a valid group gid. A property hash followed by the group gid.
The values of keys C<name> and C<description> are new group name and description.
Two arrays followed by hash. First array is for system specific roles. Format of the
array is same as output of C<group_settings> query. Second array is for realm specific roles.
One array per realm. Format of this array is same as output of C<group_settings> query.
valid system specific roles are
"API", "Add Realms", "Advanced Settings", "Global Settings", "Group Management", "License",
"Schedule Backup", "Security Settings", "System Utilities", "User Management", "View Log"
# 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.
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
( run in 1.996 second using v1.01-cache-2.11-cpan-ceb78f64989 )