NAME

VBTK::Tcp - Tcp Listener Monitoring

SYNOPSIS

  $o = new VBTK::Pop3 (
    Host           => 'pop3.nowhere.com',
    User           => 'myuser',
    Password       => 'mypass' );

  $o->addVBObj (
    VBObjName      => '.external.pop3.nowhere',
  );

  &VBTK::runAll;

DESCRIPTION

This perl library provides the ability to do simple monitoring of a POP3 server. It uses the Mail::POP3Client library (available from CPAN) to connect to a POP server, check the connection status, and disconnect. It measures the elapsed time for this and stores it. It can also retrieve messages from the mailbox and determine the latency of the message delivery from the message headers. If the connection attempt fails of takes longer than 'Timeout' seconds, then the status of the corresponding VBObjects will be set to the 'ErrorStatus' value.

Note that the 'new VBTK::Pop3' and '$o->addVBObj' lines just initialize and register the objects. It's the &VBTK::runAll which starts the monitoring.

PUBLIC METHODS

The following methods are available to the common user:

$s = new VBTK::Pop3 (<parm1> => <val1>, <parm2> => <val2>, ...)

The allowed parameters are as follows.

Interval

The interval (in seconds) on which the POP3 retrieval should be attempted. (Defaults to 300)

    Interval => 300,
Host

A string containing the pop3 host to connect to. (Required)

    Host => 'myhost',
Port

A number indicating the port to connect to. (Defaults to 110)

    Port => 110,
User

A string containing the username to use when connecting. (Required)

    User => 'me',
Password

A string containing the password to use when connecting. (Required)

    Password => 'mypass',
RetrieveFilter

A string containing a perl pattern-matching expression. If this is set, the library will retrieve and delete messages in the pop3 account which have a subject line matching this expression. It will also attempt to calculate the delivery latency of the retrieved messages.

Note that if this string is specified, the monitoring process will not send a status to the VB Server until a message matching the filter arrives. It will continue to connect to the POP3 server on the specified interval, but will not transmit a status until a message arrives. So if the process which is sending the messages dies, or some other problem prevents mail from being delivered, then the VB Object for this process will probably expire. This is a good thing, if what you're trying to monitor is the full cycle of sending an email, having it be delivered, and then retrieving it from the POP3 account.

This library is commonly used along with a VBTK::Smtp process. The VBTK::Smtp process sends mail every $Interval seconds, and the VBTK::Pop3 process gathers it every $Interval seconds. If anything breaks in between then the VBObject associated with this VBTK::Pop3 process will either get set to 'Failed' or 'Expired', and either way you can be notified.

VBHeader

An array containing strings to be used as header lines when transmitting results to the VB Server process. (Defaults to the following)

     VBHeader => [ 
         'Time              Retrieval (sec) Round-trip (sec) Error',
         '----------------- --------------- ---------------- -----' ]
VBDetail

An array containing strings to be used to format the detail lines which will be sent to the VB Server process. These strings can make use of the Perl picture format syntax. Be sure to either use single-quotes or escape out the '$' vars so that they don't get evaluated until later. (Defaults to the following)

    VBDetail => [
        '@<<<<<<<<<<<<<<<< @>>>>>>>>>>>>>> @>>>>>>>>>>>>>>> @>>>>',
        '$time,            $data[0],       $data[1],        $data[2]' ];

The following variables will be set just before these detail lines are evaluated:

$time

A datestamp of the form YYYYMMDD-HH:MM:SS

@data

An array, which contains the retrieval time in seconds, the round-trip time in seconds, and an error count. The round-trip time will always be 0 unless the 'RetrieveFilter' parm is set.

@delta

An array containing the delta's calculated between the current @data and the previous @data. In multi-row output, the row number is used to match up multiple @data arrays with their previous @data values to calulate the deltas. These deltas are most useful when monitoring the change in counters.

VBServerURI

A URI which specifies which VB Server to report results to. Defaults to the environment variable $VBURI.

    VBServerURI => 'http://vbserver:4712',
LogFile

A string containing the path to a file where a log file should be written. Leave blank if no log file is desired. (Defaults to undef).

    LogFile => '/var/log/pop3.nowhere.log',
LogHeader

Same as VBHeader, but to be used in formatting the log file.

LogDetail

Same as VBDetail, but to be used in formatting the log file.

RotateLogAt

A string containing a date/time expression indicating when the log file should be rotated. When the log is rotated, the current log will have a timestamp appended to the end of it after which logging will continue to a new file with the original name. The expression will be passed to Date::Manip so it can be just about any recognizable date/time expression. (Defaults to 12:00am)

    RotateLogAt => '12:00am',
ErrorStatus

A string containing a status to which any VBObjects should be set if there is an error while attempting to connect to the POP3 server. (Defaults to Warning).

    ErrorStatus => 'Warning',
$o = $s->addVBObj(<parm1> => <val1>, <parm2> => <val2>, ...)

The 'addVBObj' is used to define VBObjects which will appear on the VBServer to which status reports are transmitted. This method calls VBTK::Parser::addVBObj after defaulting unspecified parameters to best support monitoring a POP3 server. For a detailed description of the addVBObj parameters, see VBTK::Parser. The defaults are as follows. If you like all the defaults then you don't have to pass in any parms, except for the 'VBObjName' parm which is required.

VBObjName

This is a required parm.

    VBObjName => ".myhost.pop3",
TextHistoryLimit
    TextHistoryLimit => 30,
ReverseText

Reverse the text, so that we see the most recently reported lines first.

    ReverseText => 1,
StatusHistoryLimit

Limit to storing the last 30 status changes

    StatusHistoryLimit => 30,
StatusUpgradeRules
    StatusUpgradeRules =>
        'Upgrade to Failed if Warning occurs 3 times in <Interval * 4> seconds',
ExpireAfter
    ExpireAfter => (<Interval> * 4) seconds
Description
    Description = qq(
        This object monitors the SMTP server <Host:Port>.  If will set the status
        to warning if it is unable to connect to the POP3 server or if response
        times become unacceptable. );
RrdColumns

Save the response time, round-trip time, and error count into the Rrd database so that we can graph them.

    RrdColumns => [ '$data[0]', '$data[1]', '$data[3]' ],

In addition to passing these defaults on in a call to VBTK::Parser::addVBObj, this method captures the resulting VBTK::ClientObject pointer ($vbObj) and makes the following calls to '$vbObj->addGraphGroup':

  $vbObj->addGraphGroup (
    GroupNumber    => 1,
    DataSourceList => ':0,:1',
    Labels         => 'retrieval time (sec),round-trip time (sec)',
    Title          => 'POP3 Svr <Host:Port>',
  );

  $vbObj->addGraphGroup (
    GroupNumber    => 2,
    DataSourceList => ':2',
    Labels         => 'errors',
    Title          => 'POP3 Svr <Host:Port>',
  );

This defines two graphGroups for the VBObject. See VBTK::ClientObject for details on the 'addGraphGroup' method.

PRIVATE METHODS

The following private methods are used internally. Do not try to use them unless you know what you are doing.

To be documented...

SEE ALSO

VBTK::Server
VBTK::Parser
VBTK::ClientObject
Mail::POP3Client

AUTHOR

Brent Henry, vbtoolkit@yahoo.com

COPYRIGHT

Copyright (C) 1996-2002 Brent Henry

This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation available at: http://www.gnu.org/copyleft/gpl.html

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.