This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Symphero/Utils, Next: Sys/CpuLoad, Prev: Symphero/SimpleHash, Up: Module List Utility functions widely used by Symphero modules ************************************************* NAME ==== Symphero::Utils - Utility functions widely used by Symphero modules SYNOPSIS ======== use Symphero::Utils; or use Symphero::Utils (); # do not export any functions DESCRIPTION =========== To be extended.. EXPORTS ======= eprint(), dprint(), t2ht(), t2hf(), t2hq(), generate_key(), repair_key(), get_args(). AUTHOR ====== Andrew Maltsev, SEE ALSO ========  File: pm.info, Node: Sys/CpuLoad, Next: Sys/HostIP, Prev: Symphero/Utils, Up: Module List a module to retrieve system load averages. ****************************************** NAME ==== Sys::CpuLoad - a module to retrieve system load averages. DESCRIPTION =========== This module retrieves the 1 minute, 5 minute, and 15 minute load average of a machine. SYNOPSIS ======== use Sys::CpuLoad; print '1 min, 5 min, 15 min load average: ', join(',', CpuLoad::load()), "\n"; TO-DO ===== Support for systems without /proc/loadavg or /usr/bin/uptime by using native system calls. Ability to read CPU usage of individual CPUs on multiprocessor machines. AUTHOR ====== Clinton Wong, clintdw@netcom.com COPYRIGHT ========= Copyright (c) 1999 Clinton Wong. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Sys/HostIP, Next: Sys/Hostname, Prev: Sys/CpuLoad, Up: Module List Try really hard to get IP addr. ******************************* NAME ==== Sys::HostIP - Try really hard to get IP addr. SYNOPSIS ======== use Sys::HostIP; $ipaddr= hostip; # get (text) dotted-decimal ip AUTHOR ====== v, SEE ALSO ======== perl(1), IO::Socket, Sys::Hostname, ping, ipconfig, nbtstat, /etc/hosts  File: pm.info, Node: Sys/Hostname, Next: Sys/Lastlog, Prev: Sys/HostIP, Up: Module List Try every conceivable way to get hostname ***************************************** NAME ==== Sys::Hostname - Try every conceivable way to get hostname SYNOPSIS ======== use Sys::Hostname; $host = hostname; DESCRIPTION =========== Attempts several methods of getting the system hostname and then caches the result. It tries the first available of the C library's gethostname(), ``$Config{aphostname}`', uname(2), `syscall(SYS_gethostname)', ``hostname`', ``uname -n`', and the file `/com/host'. If all that fails it croaks. All NULs, returns, and newlines are removed from the result. AUTHOR ====== David Sundstrom <`sunds@asictest.sc.ti.com'> Texas Instruments XS code added by Greg Bacon <`gbacon@cs.uah.edu'>  File: pm.info, Node: Sys/Lastlog, Next: Sys/OutPut, Prev: Sys/Hostname, Up: Module List Provide a moderately Object Oreiented Interface to lastlog files on some Unix-like systems. *********************************************************************************************************** NAME ==== Sys::Lastlog - Provide a moderately Object Oreiented Interface to lastlog files on some Unix-like systems. SYNOPSIS ======== use Sys::Lastlog; my $ll = Sys::Lastlog->new(); while(my $llent = $ll->getllent() ) { print $llent->ll_line(),"\n"; } DESCRIPTION =========== The lastlog file provided on most Unix-like systems stores information about when each user on the system last logged in. The file is sequential and indexed on the UID (that is to say a user with UID 500 will have the 500th record in the file). Most systems do not provide a C API to access this file and programs such as 'lastlog' will provide their own methods of doing this. This module provides an Object Oriented Perl API to access this file in order that programs like 'lastlog' can written in Perl (for example the 'plastlog' program in this distribution) or that programs can determine a users last login for their own purposes. The module provides three methods for accessing lastlog sequentially, by UID or by login name. Each method returns an object of type Sys::Lastlog::Entry that itself provides methods for accessing the information for each record. METHODS ------- new The constructor of the class. Returns a blessed object that the other methods can be called on. getllent This method will sequentially return each record in the lastlog each time it is called, returning a false value when there are no more records to return. Because the lastlog file is indexed on UID if there are gaps in the allocation of UIDs on a system will there will be as many empty records returned ( that is to say if for some reason there are no UIDs used between 200 and 500 this method will nonetheless return the 299 empty records .) getlluid SCALAR $uid This method will return a record for the $uid specified or a false value if the UID is out of range, it does however perform no check that the UID has actually been assigned it must simply be less than or equal to the maximum UID currently assigned on the system. getllnam SCALAR $logname This will return the record corresponding to the user name $logname or false if it is not a valid user name. setllent Set the file pointer on the lastlog file back to the beginning of the file for repeated iteration over the file using getllent() . PER RECORD METHODS ------------------ These are the methods of the class Sys::Lastlog::Entry that give access to the information for each record. uid The UID that corresponds to this record. ll_time The time in epoch seconds of this users last login. ll_line The line (e.g. terminal ) that this user logged in via. ll_host The host from which this user logged in from or the empty string if it was a local login. EXPORT ------ None at all BUGS ==== Probably. Some systems (notoriously Red Hat Linux) may mistakenly rotate the lastlog file periodically - there is no benefit in doing this as the file will only grow if new users are added to the system and in the authors opinion it is important to keep an accurate record of all users last logins however long ago for audit and security purposes. If you are on such a system and care about this you should disable the rotation of this file. On a Red Hat system this will involve editing /etc/logrotate.conf to remove the file from the rotation. This should build on most systems given the notes in README but the author would appreciate being informed of any unusual systems where difficulty may be experienced. AUTHOR ====== Jonathan Stowe COPYRIGHT AND LICENSE ===================== Copyright Jonathan Stowe 2001. This software comes with no warranty whatsoever. This is free software and may be distributed and/or modified under the same terms as Perl itself. SEE ALSO ======== *Note Perl: (perl.info)perl,.  File: pm.info, Node: Sys/OutPut, Next: Sys/Pushd, Prev: Sys/Lastlog, Up: Module List Perl module to help make output easier. *************************************** NAME ==== Sys::OutPut - Perl module to help make output easier. SYNOPSIS ======== usage Sys::OutPut; talk $fmtstr [, @args]; out $fmtstr [, @args]; put $fmtstr [, @args]; err $fmtstr [, @args]; debug $fmtstr [, @args]; $Sys::OutPut::quiet = $::quiet; $Sys::OutPut::debug = $::debug; DESCRIPTION =========== These subroutines will make generating output to STDOUT and `STDERR' easier. All of the routines treat the *$fmtstr* argument as a printf format string, with *@args* as the format string arguments. The *talk* routine generates output to `STDERR' only if the variable `$Sys::OutPut::quiet' is non-null and non-zero. The out routine generates output to STDOUT, with a *newline* appended to <$fmtstr>, if it is not already terminated with one. The put routine generates output to STDOUT, without any additional trailing newline. The err routine generates output to `STDERR', with a *newline* appended if needed. The debug routine generates output to `STDERR' only if the variable `$Sys::OutPut::debug' is non-null and non-zero, which is also returned as the result. This allows for convenient usages such as in the following example: sub foo { ... return if debug "Stopping now."; ... next if debug "Skipping further processing"; ... } If not defined by the user, the `$Sys::OutPut::quiet' and `$Sys::OutPut::debug' variables are initialized from their corresponding main variables `$::quiet' and `$::debug', respectively, unless they are already defined. AUTHOR ====== Alan K. Stebbens BUGS ====  File: pm.info, Node: Sys/Pushd, Next: Sys/Signal, Prev: Sys/OutPut, Up: Module List change directory temporarily **************************** NAME ==== *Sys::Pushd* - change directory temporarily SYNOPSIS ======== use Sys::Pushd; { my $ignore=new Sys::Pushd '../new/dir'; # Cwd is ../new/dir } # After block exit, cwd is restored DESCRIPTION =========== Synopsis pretty much says it all. Based conceptually on SelectSaver. Multiple directories may be given, in which case they will be chdird to in order encountered. BUGS ==== Will break if immediate-destruction of objects ever ceases to be reliable in Perl. AUTHORS ======= J. Glick *jglick@sig.bsh.com*. REVISION ======== X<$Format: "`$Source$' last modified $Date$ release $SysPushdRelease$. $Copyright$"$> `Sys-Pushd/lib/Sys/Pushd.pm' last modified Tue, 09 Sep 1997 17:07:06 -0400 release 0.001. Copyright (c) 1997 Strategic Interactive Group. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Sys/Signal, Next: Sys/Syslog, Prev: Sys/Pushd, Up: Module List Set signal handlers with restoration of existing C sighandler ************************************************************* NAME ==== Sys::Signal - Set signal handlers with restoration of existing C sighandler SYNOPSIS ======== use Sys::Signal (); eval { my $h = Sys::Signal->set(ALRM => sub { die "timeout\n" }); alarm $timeout; ... do something thay may timeout ... alarm 0; }; die $@ if $@; DESCRIPTION =========== The *Sys::Signal* set method works much like `local $SIG{FOO}', but with the added functionality of restoring the underlying signal handler to the previous C function, rather than Perl's. Unless, of course, Perl's C signal handler was the previous handler. AUTHOR ====== Doug MacEachern SEE ALSO ======== perl(1).  File: pm.info, Node: Sys/Syslog, Next: Sys/UniqueID, Prev: Sys/Signal, Up: Module List Perl interface to the UNIX syslog(3) calls ****************************************** NAME ==== Sys::Syslog, openlog, closelog, setlogmask, syslog - Perl interface to the UNIX syslog(3) calls SYNOPSIS ======== use Sys::Syslog; # all except setlogsock, or: use Sys::Syslog qw(:DEFAULT setlogsock); # default set, plus setlogsock setlogsock $sock_type; openlog $ident, $logopt, $facility; syslog $priority, $format, @args; $oldmask = setlogmask $mask_priority; closelog; DESCRIPTION =========== Sys::Syslog is an interface to the UNIX `syslog(3)' program. Call `syslog()' with a string priority and a list of printf() args just like `syslog(3)'. Syslog provides the functions: openlog $ident, $logopt, $facility *$ident* is prepended to every message. *$logopt* contains zero or more of the words pid, *ndelay*, *cons*, nowait. *$facility* specifies the part of the system syslog $priority, $format, @args If *$priority* permits, logs *($format, @args)* printed as by `printf(3V)', with the addition that *%m* is replaced with `"$!"' (the latest error message). setlogmask $mask_priority Sets log mask *$mask_priority* and returns the old mask. setlogsock $sock_type (added in 5.004_02) Sets the socket type to be used for the next call to `openlog()' or `syslog()' and returns TRUE on success, undef on failure. A value of 'unix' will connect to the UNIX domain socket returned by `_PATH_LOG' in `syslog.ph'. A value of 'inet' will connect to an INET socket returned by getservbyname(). Any other value croaks. The default is for the INET socket to be used. closelog Closes the log file. Note that openlog now takes three arguments, just like `openlog(3)'. EXAMPLES ======== openlog($program, 'cons,pid', 'user'); syslog('info', 'this is another test'); syslog('mail|warning', 'this is a better test: %d', time); closelog(); syslog('debug', 'this is the last test'); setlogsock('unix'); openlog("$program $$", 'ndelay', 'user'); syslog('notice', 'fooprogram: this is really done'); setlogsock('inet'); $! = 55; syslog('info', 'problem was %m'); # %m == $! in syslog(3) SEE ALSO ======== `syslog(3)' in this node AUTHOR ====== Tom Christiansen <`tchrist@perl.com'> and Larry Wall <`larry@wall.org'>. UNIX domain sockets added by Sean Robinson <`robinson_s@sc.maricopa.edu'> with support from Tim Bunce and the perl5-porters mailing list. Dependency on `syslog.ph' replaced with XS code bu Tom Hughes <`tom@compton.nu'>.  File: pm.info, Node: Sys/UniqueID, Next: Sys/Utmp, Prev: Sys/Syslog, Up: Module List Get a guaranteed unique identifier. *********************************** NAME ==== Sys::UniqueID - Get a guaranteed unique identifier. Great for generating database keys, temporary filenames, and even gets out those tough grass stains! SYNOPSIS ======== use Sys::UniqueID; $id= uniqueid; AUTHOR ====== v, SEE ALSO ======== perl(1), Sys::HostIP  File: pm.info, Node: Sys/Utmp, Next: SyslogScan/ByGroup, Prev: Sys/UniqueID, Up: Module List Object(ish) Interface to UTMP files. ************************************ NAME ==== Sys::Utmp - Object(ish) Interface to UTMP files. SYNOPSIS ======== use Sys::Utmp; my $utmp = Sys::Utmp->new(); while ( my $utent = $utmp->getutent() ) { if ( $utent->user_process ) { print $utent->ut_user,"\n"; } } $utmp->endutent; DESCRIPTION =========== Sys::Utmp provides a vaguely object oriented interface to the Unix user accounting file ( usually /etc/utmp ). Whilst it would prefer to use the getutent() function from the systems C libraries it will attempt to provide its own if they are missing. This may not be the module that you are looking for - there is a User::Utmp which provides a different procedural interface and may well be more complete for your purposes. METHODS ------- new The constructor of the class. getutent Iterates of the records in the utmp file returning a Sys::Utmp::Utent object for each record in turn - the methods that are available on these objects are descrived below in 'PER RECORD METHODS' setutent Rewinds the file pointer on the utmp filehandle so repeated searches can be done. endutent Closes the file handle on the utmp file. PER RECORD METHODS ------------------ As mentioned above the getutent method returns an object of the type Sys::Utmp::Utent which provides methods for accessing the fields in the utmp record. There are also methods for determining the type of the record. The access methods relate to the common names for the members of the C struct utent - those provided are the superset from the Gnu implementation and may not be available on all systems: where they are not they will return the empty string. ut_user Returns the use this record was created for if this is a record for a user process. Some systems may return other information depending on the record type. If no user was set this will be the empty string. ut_id The identifier for this record - it might be the inittab tag or some other system dependent value. ut_line For user process records this will be the name of the terminalor line that the user is connected on. ut_pid The process ID of the process that created this record. ut_type The type of the record this will have a value corresponding to one of the constants (not all of these may be available on all systems and there may well be others which should be described in the getutent manpage or in /usr/include/utmp.h ) : ACCOUNTING - record was created for system accounting purposes. BOOT_TIME - the record was created at boot time. DEAD_PROCESS - The process that created this record has terminated. EMPTY - record probably contains no other useful information. INIT_PROCESS - this is a record for process created by init. LOGIN_PROCESS - this record was created for a login process (e.g. getty). NEW_TIME - record created when the system time has been set. OLD_TIME - record recording the old tme when the system time has been set. RUN_LVL - records the time at which the current run level was started. USER_PROCESS - record created for a user process (e.g. a login ) for convenience Sys::Utmp::Utent provides methods which are lower case versions of the constant names which return true if the record is of that type. ut_host On systems which support this the method will return the hostname of the host for which the process that created the record was started - for example for a telnet login. ut_time The time in epoch seconds wt which the record was created. EXPORT ------ No methods or constants are exported by default. Exportable constants -------------------- These constants are exportable under the tag ':constants': ACCOUNTING BOOT_TIME DEAD_PROCESS EMPTY INIT_PROCESS LOGIN_PROCESS NEW_TIME OLD_TIME RUN_LVL USER_PROCESS BUGS Probably. This module has been tested on Linux, Solaris, FreeBSD ,SCO Openserver and SCO UnixWare and found to work on those platforms. If you have difficulty building the module or it doesnt behave as expected then please contact the author including if appropriate your /usr/include/utmp.h AUTHOR ====== Jonathan Stowe, LICENCE ======= This Software is Copyright Netscalibur UK 2001. This Software is published as-is with no warranty express or implied. This is free software and can be distributed under the same terms as Perl itself. SEE ALSO ======== *Note Perl: (perl.info)perl,.  File: pm.info, Node: SyslogScan/ByGroup, Next: SyslogScan/Delivery, Prev: Sys/Utmp, Up: Module List Organizes a Summary of mail statistics into Groups of related e-mail users ************************************************************************** NAME ==== SyslogScan::ByGroup - Organizes a Summary of mail statistics into Groups of related e-mail users SYNOPSIS ======== # $summary is a SyslogScan::Summary object # default is to organize by internet host my $byGroup = new SyslogScan::ByGroup($summary); print $byGroup -> dump(); # group by whether users use 'jupiter' or 'satellife' as # their machine name, and discard users who use neither my $pointerToGroupingRoutine = sub { my $address = shift; return 'jupiter' if $address =~ /jupiter.healthnet.org$/; return 'satellife' if $address =~ /satellife.healthnet.org$/; # ignore all others return undef; } my $groupByMachine = new SyslogScan::ByGroup($summary, $pointerToGroupingRoutine); print $groupByMachine -> dump(); # Extract a SyslogScan::Group object my $jupiterGroup = $$groupByMachine{jupiter}; print $jupiterGroup -> dump(); # Extract a SyslogScan::Summary object my $summaryOfJupiter = $jupiterGroup{byAddress}; print $summaryOfJupiter -> dump(); # Create a summary by group, rather than a summary by address my $summaryByMachine = $groupByMachine -> createSummary(); DESCRIPTION =========== A SyslogScan::ByGroup object is a hash table of SyslogScan::Group objects, each indexed by the group name as returned by the sorting algorithm fed to 'new'. A SyslogScan::Group is a hash table with two members: 'byAddress', which is a SyslogScan::Summary of each address which is a member of the Group, and 'groupUsage', which is a SyslogScan::Usage object containing the total usage of the group. AUTHOR and COPYRIGHT ==================== The author (Rolf Harold Nelson) can currently be e-mailed as rolf@usa.healthnet.org. This code is Copyright (C) SatelLife, Inc. 1996. All rights reserved. This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 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. SEE ALSO ======== *Note SyslogScan/Summary: SyslogScan/Summary,, *Note SyslogScan/Usage: SyslogScan/Usage,  File: pm.info, Node: SyslogScan/Delivery, Next: SyslogScan/DeliveryIterator, Prev: SyslogScan/ByGroup, Up: Module List encapsulates a logged, successful delivery of mail from a sender to a list of recipients. ***************************************************************************************** NAME ==== SyslogScan::Delivery - encapsulates a logged, successful delivery of mail from a sender to a list of recipients. SYNOPSIS ======== see *Note SyslogScan/DeliveryIterator: SyslogScan/DeliveryIterator, DESCRIPTION =========== A 'Delivery' object is an indication that mail was successfully delivered or forwarded from a sender to a list of recipients. You can extract Delivery objects from a syslog file by using *Note SyslogScan/DeliveryIterator: SyslogScan/DeliveryIterator,. Variables --------- my $delivery = $iter -> next(); #----------------------------------------- # Sender, ReceiverList, Size, and Date are the most useful #----------------------------------------- # e-mail address of sender, may be 'undef' if the sender # could not be determined from the syslog my $sender = $$delivery{Sender}; # reference to array of e-mail addresses of recipients my $paReceiverList = $$delivery{ReceiverList}; my @aReceiverList = @$paReceiverList; print "The recipient(s) of the message was (were) ", join(' ',@aReceiverList), "\n"; # size of message, may be 'undef' if the size could not be # determined from the syslog my $sizeInBytes = $$delivery{Size}; # date the message was succesfully delivered or forwarded my $date = $$delivery{Date}; #----------------------------------------- # Id and Instance are more advanced features #----------------------------------------- # 'id' in syslog, useful for cross-referencing my $id = $$delivery{Id}; # The first delivery of any message has Instance of 1; the next # deliveries will have Instance > 1, specifically a number equal to # the number of people who the message has previously been delivered # to, plus 1. This is useful for detecing mass-mailings. # Suppose I send a message to 5 people, but only three copies are # delivered right away, the other two are deferred. The first # Delivery has instance 1; the next delivery of the same message # will have instance 4. my $instance = $$delivery{Instance}; my @aReceiverList = @{$$delivery{ReceiverList}}; print "This message has so far been delivered to ", $instance + $@aReceiverList - 1, "people so far\n"; METHODS ======= # Manually create a new Delivery object. my $delivery = new SyslogScan::Delivery (Date => time(), Size => 100, From => 'foo@bar.com', ReceiverList => [him@baz.edu, her@baz.edu], Instance => 1, Id => 'manual' . $id++); # print out contents, either in summary or in verbose mode print $delivery -> summary(); print $delivery -> dump(); # save/restore delivery to/from file open(OUT,">save.txt"); $delivery -> persist(\*OUT); close(OUT); undef($delivery); open(IN,"save.txt"); $delivery = SyslogScan::Delivery -> restore(\*IN); # $delivery is restored to its original state SUPPORT ======= E-mail bugs to rolf@usa.healthnet.org. AUTHOR and COPYRIGHT ==================== This code is Copyright (C) SatelLife, Inc. 1996. All rights reserved. This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself. IN NO EVENT SHALL THE AUTHORS 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. SEE ALSO ======== *Note SyslogScan/DeliveryIterator: SyslogScan/DeliveryIterator,, *Note SyslogScan/Summary: SyslogScan/Summary,  File: pm.info, Node: SyslogScan/DeliveryIterator, Next: SyslogScan/SendmailLine, Prev: SyslogScan/Delivery, Up: Module List scans a syslog file for "deliveries", successful transfers of mail to mailboxes or to other machines. ***************************************************************************************************** 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=, 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=, delay=00:00:05, mailer=fidogate, stat=Deferred (Remote host is busy) ... Jun 13 14:55:50 satellife sendmail[29558]: DAA29556: to=, 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. This code is Copyright (C) SatelLife, Inc. 1996. All rights reserved. This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 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. SEE ALSO ======== *Note SyslogScan/Delivery: SyslogScan/Delivery,, *Note SyslogScan/Summary: SyslogScan/Summary,  File: pm.info, Node: SyslogScan/SendmailLine, Next: SyslogScan/SendmailLineFrom, Prev: SyslogScan/DeliveryIterator, Up: Module List Enhances basic SyslogEntry parsing by understanding sendmail to/from message syntax. ************************************************************************************ NAME ==== SyslogScan::SendmailLine - Enhances basic SyslogEntry parsing by understanding sendmail to/from message syntax. DESCRIPTION =========== Suppose I run a 'new SyslogEntry' command and read in the following line: Jun 13 01:32:26 satellife sendmail[23498]: WAA18677: to=bar@foo.org,baz@foo.org, delay=03:50:20, mailer=smtp, relay=relay.ulthar.com [128.206.5.3], stat=Sent (May, have (embedded, commas)) If I have not loaded in SendmailLine, then 'new SyslogEntry' will return an 'UnsupportedEntry' object looking like this: month => Jun, day => 13, time => 01:32:26, machine => satellife, executable => sendmail, tag => 23498, content => WAA18677: to=bar@foo.org,baz@foo.org, delay=03:50:20, ... On the other hand, if I have a 'use SyslogScan::SendmailLine' command before my call to 'new SyslogEntry', then I will a 'SendmailLine' object with all of the above parameters, plus the following additional parameters: messageID => WAA18677 toList => ( bar@foo.org, baz@foo.org ) attrHash => ( to => "bar@foo.org,baz@foo.org", delay => "03:50:20", mailer => "smtp", relay => "relay.ulthar.com [128.206.5.3]", stat => "Sent (May, have (embedded, commas))" ) Also well-supported is the 'From' line: Jun 13 01:34:54 satellife sendmail[26035]: BAA26035: from=, size=7000, class=0, pri=37000, nrcpts=1, msgid=<199606130634.BAA26035@satellife.healthnet.org>, proto=SMTP, relay=uth.bar.com [155.247.14.2] will produce a SendmailLine object with the additional attributes of messageID => BAA26035 attrHash => ( from => "", size => "7000", class => "0", pri => "37000" nrcpts => "1", msgid => "<199606130634.BAA26035@satellife.healthnet.org>", proto => "SMTP", relay => "uth.bar.com [155.247.14.2]" ) Other types of lines are legal, but are not currently very thorougly parsed, and therefore return somewhat minimal SendmailLine objects. Jun 13 13:05:35 satellife sendmail[19620]: NAA19606: NAA19620: return to sender: unknown mailer error 2 will return a SendmailLine object with the usual SyslogEntry attributes, plus the single additional attribute of messageID => NAA19606 while lines like the following produce SendmailLine objects with no additional SendmailLine-specific attributes: Jun 13 03:00:05 satellife sendmail[26611]: alias database /var/yp/nis.healthnet.org/mail.aliases rebuilt by root Note this is a subclass for SyslogScan::SyslogEntry which handles certain types of logfile lines. See the documentation for SyslogEntry for further details of how SyslogEntry subclassing works. Also, see the SyslogScan::SendmailLineFrom and SyslogScan::SendmailLineTo modules for examples of returned SendmailLine objects. AUTHOR and COPYRIGHT ==================== The author (Rolf Harold Nelson) can currently be e-mailed as rolf@usa.healthnet.org. This code is Copyright (C) SatelLife, Inc. 1996. All rights reserved. This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 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. SEE ALSO ======== *Note SyslogScan/SyslogEntry: SyslogScan/SyslogEntry,, *Note SyslogScan/SendmailLineFrom: SyslogScan/SendmailLineFrom,, *Note SyslogScan/SendmailLineTo: SyslogScan/SendmailLineTo,  File: pm.info, Node: SyslogScan/SendmailLineFrom, Next: SyslogScan/SendmailLineTo, Prev: SyslogScan/SendmailLine, Up: Module List encapsulates a 'From:' line in a syslog file ******************************************** NAME ==== SyslogScan::SendmailLineFrom - encapsulates a 'From:' line in a syslog file DESCRIPTION =========== Here is a sample SendmailLineFrom object. If 'new SyslogScan::SendmailLineEntry' reads in a line like Jun 13 02:34:54 satellife sendmail[26035]: BAA26035: from=, size=7000, class=0, pri=37000, nrcpts=1, msgid=<199606130634.BAA26035@satellife.healthnet.org>, proto=SMTP, relay=vm.temple.edu [155.247.14.2] then it will return a SyslogScan::SendmailLineFrom object like this: # generic SyslogScan::SyslogEntry stuff day => 13, executable => 'sendmail', machine => 'satellife', month => 'Jun', tag => 26035, time => '02:34:54', content => 'BAA26035: from=, size=7000, class=0, pri=37000, nrcpts=1, msgid=<199606130634.BAA26035@satellife.healthnet.org>, proto=SMTP, relay=vm.temple.edu [155.247.14.2]', # sendMailLineFrom-specific stuff messageID => 'BAA26035', attrHash => { 'class' => 0, 'from' => 'help-net@bar.temple.edu', 'msgid' => '<199606130634.BAA26035@satellife.healthnet.org>', 'nrcpts' => 1, 'pri' => 37000, 'proto' => 'SMTP', 'relay' => 'vm.temple.edu [155.247.14.2]', 'size' => 7000 } AUTHOR and COPYRIGHT ==================== The author (Rolf Harold Nelson) can currently be e-mailed as rolf@usa.healthnet.org. This code is Copyright (C) SatelLife, Inc. 1996. All rights reserved. This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 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. SEE ALSO ======== *Note SyslogScan/SendmailLine: SyslogScan/SendmailLine,  File: pm.info, Node: SyslogScan/SendmailLineTo, Next: SyslogScan/SendmailUtil, Prev: SyslogScan/SendmailLineFrom, Up: Module List encapsulates a 'To:' line in a syslog file ****************************************** NAME ==== SyslogScan::SendmailLineTo - encapsulates a 'To:' line in a syslog file DESCRIPTION =========== Here is a sample SendmailLineTo object. If 'new SyslogScan::SendmailLineEntry' reads in a line like Jun 13 01:50:48 satellife sendmail[23498]: WAA18677: to=mbe527@time.nums.nwu.edu,jsm341@anima.nums.nwu.edu, delay=03:52:42, mailer=smtp, relay=anima.nums.nwu.edu. [165.124.50.10], stat=Sent (AA097917369 Message accepted for delivery) then it will return a SyslogScan::SendmailLineTo object like this: # generic SyslogScan::SyslogEntry stuff day => 13, executable => 'sendmail', machine => 'satellife', messageID => 'WAA18677', month => 'Jun', tag => 23498, content => 'WAA18677: to=mbe527@time.nums.nwu.edu,jsm341@anima.nums.nwu.edu, delay=03:52:42, mailer=smtp, relay=anima.nums.nwu.edu. [165.124.50.10], stat=Sent (AA097917369 Message accepted for delivery)', # sendMailLineTo-specific stuff messageID => 'WAA18677' toList => (mbe527@time.nums.nwu.edu, jsm341@anima.nums.nwu.edu) attrHash => ( 'delay' => '03:52:42', 'mailer' => 'smtp', 'relay' => 'anima.nums.nwu.edu. [165.124.50.10]', 'stat' => 'Sent (AA097917369 Message accepted for delivery)', 'to' => 'mbe527@time.nums.nwu.edu,jsm341@anima.nums.nwu.edu' ) AUTHOR and COPYRIGHT ==================== The author (Rolf Harold Nelson) can currently be e-mailed as rolf@usa.healthnet.org. This code is Copyright (C) SatelLife, Inc. 1996. All rights reserved. This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 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. SEE ALSO ======== *Note SyslogScan/SendmailLineTo: SyslogScan/SendmailLineTo,  File: pm.info, Node: SyslogScan/SendmailUtil, Next: SyslogScan/Summary, Prev: SyslogScan/SendmailLineTo, Up: Module List utilities for sendmail packages. ******************************** NAME ==== SendmailUtil.pm - utilities for sendmail packages. SYNOPSIS ======== use SyslogScan::SendmailUtil; open(FH,"/var/log/syslog"); my $transfer; while ($transfer = SyslogScan::SendmailUtil::getNextMailTranfer(\*FH)) { # process the tranfer } DESCRIPTION =========== getNextMailTransfer queries a filehandle pointing to a syslog for the next line which is a sendmail 'To:', 'From:', and 'Clone:' lines, and returns a SyslogScan::SendmailLineFrom, SyslogScan::SendmailLineTo, or SyslogScan::SendmailLineClone object. canonAddress() routine ====================== The canonAddress() routine modifies the address of the Sendmail routines to be all-lowercase, remove enclosing brackets, and append '@localhost' to local addresses. Modifying this routine will change how SyslogScan canonicalizes. AUTHOR and COPYRIGHT ==================== The author (Rolf Harold Nelson) can currently be e-mailed as rolf@usa.healthnet.org. This code is Copyright (C) SatelLife, Inc. 1996. All rights reserved. This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 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. SEE ALSO ======== *Note SyslogScan/SendmailLineFrom: SyslogScan/SendmailLineFrom,, *Note SyslogScan/SendmailLineTo: SyslogScan/SendmailLineTo,, *Note SyslogScan/SyslogEntry: SyslogScan/SyslogEntry,  File: pm.info, Node: SyslogScan/Summary, Next: SyslogScan/SyslogEntry, Prev: SyslogScan/SendmailUtil, Up: Module List encapsulates a tally of how many bytes people have sent and received through sendmail ************************************************************************************* NAME ==== SyslogScan::Summary - encapsulates a tally of how many bytes people have sent and received through sendmail SYNOPSIS ======== Use SyslogScan::Summary; Use SyslogScan::DeliveryIterator; my $iter = new SyslogScan::DeliveryIterator(syslogList => [/var/log/syslog]); my $summary; if (defined $DOING_IT_THE_HARD_WAY_FOR_NO_PARTICULAR_REASON) { # feed a series of SyslogScan::Delivery objects $summary = new SyslogScan::Summary(); my $delivery; while ($delivery = $iter -> next()) { $summary -> registerDelivery($delivery); # You would instead use: # $summary -> registerDelivery($delivery,'foo\.com\.$') # if you only cared to get statistics relating to how # much mail users at foo.com sent or received. } } else { # slurps up all deliveries in the iterator, # producing the same effect as the block above $summary = new SyslogScan::Summary($iter); } print $summary -> dump(); use SyslogScan::Usage; my $usage = $$summary{'john_doe@foo.com'}; if (defined $usage) { print "Here is the usage of John Doe at foo.com:\n"; print $usage -> dump(); } else { print "John Doe has neither sent nor received messages lately.\n"; } DESCRIPTION =========== A SyslogScan::Summary object will 'register' a series of SyslogScan::Delivery objects. All registered deliveries are grouped by sender and receiver e-mail addresses, and then added up. Three sums are kept: Total Bytes Recieved, Total Bytes Sent, and Total Bytes Broadcast. Methods ------- static new() method new takes as arguments a (possibly null) list of SyslogScan::DeliveryIterator objects, from which it extracts and registers all queued deliveries. registerDelivery() method *registerDelivery* takes as its first argument a SyslogScan::Delivery object followed by up to two optional patterns. If the first pattern is specified, only those e-mail addresses which match the pattern are tallied. This enables you to create an accounting summary for only those users at your site. If the second pattern is also specified, then deliveries will only be registered to the person matched by the first pattern if the second pattern matches the address at 'the other end of the pipe'. Pattern-matches are case-insensitive. Remember the '(?!regexp)' operation if you want only addresses which do _not_ match the pattern to get passed through the filter. For example, if mail to or from 'support' is exempt from billing charges, note that the pattern-match /^(?!support)/ does _not_ match 'support@foo.com' but _does_ match 'random_guy@foo.com'. registerAllInIterators() method Takes as parameters two patterns and a list of iterators, then feeds deliveries in the iterators and the patterns to registerDelivery(). For example: $sum -> registerAllInIterators('foo\.com$','^(?!.*bar\.com$)',@iterList) will bill users at foo.com for all mail extracted from @iterList which was sent from foo.com to somewhere besides bar.com, or sent to foo.com from somewhere besides bar.com. dump() method dump returns a string containing address lines alternating with usage reports. Usage reports are in the form: B#,Bb S#,Sb R#,Rb Where: B# is the number of messages broadcast B# is the total number of bytes broadcast S# is the number of messages sent S# is the total number of bytes sent R# is the number of messages received R# is the total number of bytes received persist() method *persist* takes as its single argument an output file-handle, and then persists the state of the summary to the file. static restore() method restore takes as its single argument an input file-handle which stores the results of a previous persist() command, and then returns a copy of the object in the state in which it was originally persisted. addSummary() method *addSummary* takes as its single argument a second SyslogScan::Summary object, and then adds this second summary to the $self object. Example of use -------------- Suppose I have a function getTodaySummary() which gets a Summary of the last 24 hours of sendmail logging. my $summary = getTodaySummary(); open(SUMMARY1,">summary1.sav"); $summary -> persist(\*SUMMARY1); close(SUMMARY1); exit 0; # wait 24 hours my $summary = getTodaySummary(); open(SUMMARY2,">summary2.sav"); $summary -> persist(\*SUMMARY2); close(SUMMARY2); exit 0; # some time later, you decide you want a summary of the total # for both days. So, you write this program: open(INSUM1,"summary1.sav"); my $sum = SyslogScan::Summary -> restore(\*INSUM1); open(INSUM2,"summary2.sav"); my $sum2 = SyslogScan::Summary -> restore(\*INSUM2); $sum -> addSummary($sum2); print "Here is the grand total for both days:\n\n"; print $sum -> dump(); Internals --------- A SyslogScan::Summary object is a hash of SyslogScan::Usage objects, where the key is the e-mail address of the user in question. SyslogScan::Usage has its own man page which describes how to extract information without having to use the dump() method. AUTHOR and COPYRIGHT ==================== The author (Rolf Harold Nelson) can currently be e-mailed as rolf@usa.healthnet.org. This code is Copyright (C) SatelLife, Inc. 1996. All rights reserved. This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 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. SEE ALSO ======== *Note SyslogScan/Usage: SyslogScan/Usage,, *Note SyslogScan/DeliveryIterator: SyslogScan/DeliveryIterator,, *Note SyslogScan/Delivery: SyslogScan/Delivery,, *Note SyslogScan/ByGroup: SyslogScan/ByGroup,  File: pm.info, Node: SyslogScan/SyslogEntry, Next: SyslogScan/Usage, Prev: SyslogScan/Summary, Up: Module List parses generic lines in syslog files. ************************************* NAME ==== SyslogScan::SyslogEntry - parses generic lines in syslog files. SYNOPSIS ======== use SyslogScan::SyslogEntry; open(FH,"/var/log/syslog"); my $entry; # reads from filehandle $fh and returns an object # of a subclass of SyslogEntry. while ($entry = new SyslogScan::SyslogEntry (\*FH)) { # process $entry } DESCRIPTION =========== All Syslog object share these data structures: month, day, time, machine, executable, tag (optional), content. For example, if a syslog line looks like: Jun 13 02:32:27 satellife in.identd[25994]: connect from mail.missouri.edu then the line returned by 'new SyslogEntry' will return a SyslogEntry-derived object with at least this set of parameters: month => Jun, day => 13, time => 02:32:27, machine => satellife, executable => in.identd, tag => 25994, content => connect from mail.missouri.edu, unix_time => 834633147, raw => Jun 13 02:32:27 satellife in.identd[25994]: connect from mail.missouri.edu Since the executable is 'in.identd', SyslogEntry.pm will look for a class called "SyslogScan::In_identdLine" derived from SyslogEntry, and attempt to call that class's parseContent method. If no such In_identdLine class is in use, then the returned object is of the default "SyslogScan::UnsupportedEntry" class. If the In_identdLine class throws a die() exception, SyslogEntry.pm will catch the die() and return a "SyslogScan::BotchedEntry" object containing the exception in "$errorString" and the failed handler in "brokenHandler". "new SyslogEntry" returns the undefined value if at EOF. BUGS ==== In retrospect, this model of passing control to subclasses based on the name of the controlling program doesn't work exceptionally elegantly in perl. I would probably do it more conventionally if I had it to do over again. AUTHOR and COPYRIGHT ==================== The author (Rolf Harold Nelson) can currently be e-mailed as rolf@usa.healthnet.org. Thanks to Allen S. Rout for his code contributions. This code is Copyright (C) SatelLife, Inc. 1996. All rights reserved. This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 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. SEE ALSO ======== *Note SyslogScan/SendmailLine: SyslogScan/SendmailLine,