AnyEvent-Porttracker

 view release on metacpan or  search on metacpan

Porttracker.pm  view on Meta::CPAN

}

=item $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 C<none>, C<login_cram_md6> or C<login> methods,
in this order of preference (typically, C<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:

=over 4

=item host => $hostname [MANDATORY]

The hostname or IP address of the Porttracker box.

=item port => $service

The service (port) to use (default: C<porttracker=55>).

=item 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).

=item 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

Porttracker/protocol.pod  view on Meta::CPAN

=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.

Porttracker/protocol.pod  view on Meta::CPAN

=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

Porttracker/protocol.pod  view on Meta::CPAN

=back

=back


=head2 REQUESTS AND RESPONSES

=over 4

=item "login" - username/password-based authentication

   > [<id>, "login", <username>, <password>]
   < [<id>, 1]

Tries to log-in with the given username and password. The username
and password must belong to a valid admin user configured in the user
interface.

=item "login_cram_md6" - secure username/password-based authentication

   > [<id>, "login_cram_md6", <username>, <cr>, <cc>]
   < [<id>, 1, <sr>]

Tries to securely login with a username and password. First, a shared key
is calculated, by using (all MD6 invocations are with blocksize 64 and
hashsize 256):

   key = hmac_md6 (password, username) # as defined by RFC 2104

Then, the client generates a a nonce of any length (empty nonces are ok),
called C<cc>. Then it calculates C<cr> using the C<key>, C<cc> and the
server C<nonce> as follows ("+" means concatenation):

   cr = hmac_md6 (key, cc + nonce)

Then it sends both C<cr> and C<cc> in the login request, base64-encoded.

If authentication is successful, the server responds with a base64-encoded

Porttracker/protocol.pod  view on Meta::CPAN

   sr = hmac_md6 (key, nonce + cc)

If the client used a non-empty C<cc>, then it can use the C<sr> value to
shield against man-in-the-middle attacks by comparing it with its own
calculation.

Test vectors:

   nonce/base64  = YWVlYWJkZjQzMWEzYWM2
   username/text = user
   password/text = pass
   key/base64    = C1JQ4jnjsrBzJtTZXt8Po+wA/iXtaM5r4BIIjl0lfMA
   cc/base64     = ZmZiOTczMjE=
   cr/base64     = 5UJKUqehqBKwXiSk6RzYjsPWqivMJcEgE2crTLVyw04
   sr/base64     = gGKEpOuv5WuuQ7ZbwDWNIdyJtAnCimVN/faM5qWtOZM

=item "ping" - ping the server, return some informational data

   > [<id>, "ping"]
   < [<id>, 1, <timestamp>, <server-pid>]

Porttracker/protocol.pod  view on Meta::CPAN

   > [<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.

Porttracker/protocol.pod  view on Meta::CPAN

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.

Porttracker/protocol.pod  view on Meta::CPAN

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:

Porttracker/protocol.pod  view on Meta::CPAN

                            [["Add Realms",0]]], [["386550063117151",[["Poller Setting",1]]]]]
   < [1, 1]


   > [1, "group_settings_modify", "98784248723", {},
                            [["Add Realms",0],["Global Settings",1]]]
   < [1, 1]

=item "remote_backup" - runs the remote backup immediately

   > [<id>, "remote_backup", <protocol>, <host>, <user>, <password>,
                             <directory>, <email-recipient>]
   < [<id>, 1]

This request can be made without any arguments. When its requested without 
arguments make sure backup settings configured in GUI. The valid values for 
C<protocol> are C<SCP> and C<FTP>. The C<email-recipient> and C<directory> 
arguments are optional.

Example:

README  view on Meta::CPAN

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