view release on metacpan or  search on metacpan

Porttracker/protocol.pod  view on Meta::CPAN

All messages are JSON arrays in one of the following formats:

   [<id>, <type>, <args...>]        # client request
   [<id>, <status>, <args...>]      # server response
   [null, <type>, <args...>]        # server notification

The first member, C<id>, identifies the request/response pair: Each
request the client sends has to use a unique ID not currently in use
by any request that is still ongoing. Any string or number can be
used for the C<id> value. The C<type> member is a string indicating
the type of request to the server. The remaining members (if any) are
request-specific.

Each server response to a request will use the same C<id> value as the
request. The second member, C<status>, is either C<0> for failure,
followed by an error message and optionally more information, or C<1> for
success and request-specific return values.

The protocol supports pipelining (sending multiple requests without
processing any replies) and responses to a request can come in any
order. Most requests will be handled in parallel, only some (like the
login messages) are guaranteed to get processed in order.

If the first member is the JSON C<null> value, then the message is a
server notification and the C<type> member identified the notification
type. This mechanism is used for the initial server greeting and any fatal
errors (such as wrongly formatted client requests).

Note: The type model used for JSON is "soft", that is, numbers might
sometimes be returned as strings, and vice versa. The only values in the
protocol where you can be sure of the type are the C<id> and status return
values, for other values you have to be liberal in what you accept.


=head1 SESSION STRUCTURE

When connecting, the server sends a server greeting notification
("hello"), informing the client of the protocol version, whether
authentication is required and which kind of authentication is supported.

If the server indicated that authentication is required, the client will
then have to send login requests until it successfully authenticated.

After that, the server will continue serving client requests.

To end a session, the client just should simply drop the connection.


=head1 EXAMPLE SESSION

   < [null,"hello",1,["login"]]
     Server sent the initial greeting and requests the
     use of a login request for authentication.

   > ["someid", "realm_poll", 5100005442]
   < ["someid",0,"you need to authenticate first"]
     Most requests are only valid once logged-in.

   > [100, "login", "username", "password"]
   < [100,1]
     The client sent a login request with credentials,
     and the server accepted them.

   > ["someid", "realm_poll", 5100005442]
     Starts a poll, which takes a long time.

   > [3, "ping"]
   < [3,1,1202674637.64799,17372]
     Ping simply returns a timestamp and the daemon pid as fast as possible.

   > ["someid",1,{"port_updates":"2","device_seens":"88","device_inserts":"9","switch_updates":"3","port_seens":"73"}]
     The result of the poll, with some statistical data.


=head1 MESSAGE TYPES

Messages might contain more than the documented number of array
members. If that is the case, the application must simply ignore them.

=head2 NOTIFICATIONS

=over 4

=item "hello" - initial server greeting

   < [null, "hello", <version>, [<auth-types...>], <nonce>]

The server usually sends this notification after the initial connect and
never thereafter. The C<version> argument specified the protocol version
(always C<1>), the C<auth-types> argument is an array of authentication
types that the server accepts (there can be more than one). The nonce can
be used to securely authenticate, and is base64-encoded.

Before a client is authenticated, all other requests will fail.

The defined authentication types are:

=over 4

=item "none"

No additional authentication is required, the client can simply
start sending other requests. This is available when the server
detects a "secure" connection, e.g. from the local host, or when other
authentication methods are used, such as an SSL certificate or IP-based
authentication.

=item "login"

The client may use password authentication by sending a login request
(described later).

=item "login_cram_md6"

The client may use a challenge response mechanism based on MD6 to authenticate.

=back

=item "info" - an informational message

   < [null, "info", <informational-message>]

Porttracker/protocol.pod  view on Meta::CPAN

   > [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
algorithm and privacy algorithm.

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