NAME

SyslogScan::DeliveryIterator -- scans a syslog file for "deliveries", successful transfers of mail to mailboxes or to other machines.

SYNOPSIS

    use SyslogScan::Delivery;
    use SyslogScan::DeliveryIterator;
    
    my $iter = new SyslogScan::DeliveryIterator(syslogList =>
                                                ["/var/log/syslog"]);
    
    my $delivery;
    while ($delivery = $iter -> next())
    {
        print $delivery -> summary();
    }

DESCRIPTION

A DeliveryIterator goes through your sendmail logging file (which may be /var/log/syslog, /var/adm/messages, or something completely different) looking for successful deliveries of mail to local user-accounts or successful transfers of mail to remote machines.

Here is an excerpt from a sample syslog:

Jun 13 01:50:16 satellife sendmail[29556]: DAA29556: from=<shookway@fs1.ho.man.ac.uk>, size=954, class=0, pri=30954, nrcpts=1, msgid=<5B013544E0D@fs1.ho.man.ac.uk>, proto=ESMTP, relay=curlew.cs.man.ac.uk [130.88.13.7]

Jun 13 01:50:17 satellife sendmail[29558]: DAA29556: to=<shoko@time.healthnet.org>, delay=00:00:05, mailer=fidogate, stat=Deferred (Remote host is busy)

...

Jun 13 14:55:50 satellife sendmail[29558]: DAA29556: to=<shoko@time.healthnet.org>, delay=13:00:05, mailer=fidogate, stat=Sent

The delivery is not registered until 14:55:50. In order to figure out the size and sender, the iterator needs to have gone over the 'from' entry associated with message DAA29566, otherwise it will return a delivery with 'Sender' and 'Size' set to an undefined value (unless you specified defaults when constructing your DeliveryIterator.)

METHOD 'NEW'

'new' creates a new iterator.

    my $iter =
        new SyslogScan::DeliveryIterator(startDate => "06.01.96 18:00:00",
                                         endDate => "06.02.96 06:00:00",
                                         syslogList =>
                                         [/var/log/syslog.090696,
                                          /var/log/syslog.090796],
                                         unknownSender => 'antiquity',
                                         unknownSize => 0,
                                         defaultYear => 1996);

All of the above parameters are optional.

startDate and endDate define a span of time; we ignore deliveries that fall before startDate or after endDate. This allows you to generate statistical reports about mail delivered over a given span of time.

syslogList is a list of files to search through for deliveries. The alternative to specifying syslogList is to supply a file-handle to a syslog file on each call to the next() method.

unknownSender and unknownSize are what to specify as the sender and the size if we cannot determine from the logs who sent the message and how large the message is.

defaultYear is the year in which the deliveries are assumed to have taken place (this is not specified in the syslog file.) Default is to guess the year that makes the delivery take place close to now. (For example, if 'now' is February 3rd 1996, then by default a delivery made on December 14th is assumed to be in 1995, and a delivery made on February 4th is assumed to be in 1996.

defaultYear is deprecated, set the default year instead with SyslogScan::ParseDate::setDefaultYear.

METHOD 'NEXT'

Once an iterator is defined, the next() method will search for the next delivery, skipping any deliveries which don't match the time constraints of startDate and endDate. There are two ways to call next():

    # poll syslogList members
    $delivery = $iter -> next;

    # poll filehandle
    open(LOG,"/var/log/syslog");
    $delivery = $iter -> next(\*LOG);

OTHER OPERATIONS

The 'appendSyslog' method can add a syslog filename to the list of syslog filenames which were specified at construction time as 'syslogList'.

Setting the global variable $::gbQuiet to 1 will suppress some of the error messages to STDERR.

BUGS

If two messages have the same message ID through a bad coincidence, a message is produced with sender of 'duplicate' and size of '0' rather than using the unknownSender and unknownSize parameters.

Sender and receiver address are downcased automatically. It would probably be better if this module downcased only the host-name part of the address and not the user-name.

Some mailings have a 'ctladdr' field; DeliveryIterator should probably try to parse this as a backup clue for figuring out the sender.

AUTHOR and COPYRIGHT

The author (Rolf Harold Nelson) can currently be e-mailed as rolf@usa.healthnet.org.

In no event shall SatelLife be liable to any party for direct, indirect, special, incidental, or consequential damages arising out of the use of this software and its documentation (including, but not limited to, lost profits) even if the authors have been advised of the possibility of such damage.