NAME
     Parse::EventLog - Parse information from Windows Event Logs

SYNOPSIS
    use Parse::EventLog;
    my $elog =
     Parse::EventLog->new("c:\\winnt\\system32\\config\\SysEvent.Evt");

    my %c = $elog->getNewestEvent();
    # Do something interesting here.

    while (%c = $elog->getPreviousEvent()) {
     print localtime($c{TimeGenerated}) .
      ": $c{EventID} generated by $c{Source} on $c{Computer}.\n";
     # Do a lot of interesting somethings here.
    }

DESCRIPTION
   Parse::EventLog is a module designed to allow parsing of binary Windows
   2000+ Event Logs on any platform. For better Event Log parsing on
   Windows platforms, see Win32::EventLog.

   When instansiated with the location of an Event Log file, you will be
   able to walk through the existing events in chronological order from
   oldest to newest or vice versa, as well as being able to extract the
   whole log to a hash table and seek through however you wish.

METHODS
 new
    my $eventlog =
     Parse::EventLog->new("c:\\winnt\\system32\\config\\SysEvent.Evt");

   Parse::EventLog constructor, called with the location of the event log
   file to open. Returns a Parse::EventLog object or dies on error. Stores
   the internal record pointer at the newest event, so the next call to
   getPreviousEvent will succeed but getNextEvent will fail (there are no
   newer events).

 getOldestEvent
    my %event = $eventlog->getOldestEvent();

   Returns a hash table containing the oldest entry in the event logand
   moves the current event pointer to the oldest event.

 getNewestEvent
    my %event = $eventlog->getNewestEvent();

   Returns a hash table containing the newest entry in the event log and
   moves the current event pointer to the newest event.

 getNextEvent
    my %event = $eventlog->getNextEvent();

   Moves us forward in time, returning a hash table containing the next
   event in the event log. Returns an empty array/hashtable if there are no
   more events to get.

 getPreviousEvent
    my %event = $eventlog->getPreviousEvent();

   Moves us backward in time, returning a hash table containing the
   previous event in the event log. Returns an empty array/hashtable if
   there are no more events to get.

 getAll
    my %event = $eventlog->getAll();

   Returns a copy of the internal Event Log hash table for your own
   nefarious pleasure. The main hash table is keyed by the internal
   RecordNumber (which is unique to each entry in the file). The value of
   each of those keys is another hash table containing the actual event (in
   the same format as is returned by the other get*Event functions).

  Example
    my %c = $eventlog->getAll();
    foreach my $a (keys %c) {
     print 'Time: ' . localtime($c{$a}{'TimeGenerated'} . "\n";
     print "Computer: $c{$a}{'Computer'}\n";
     print "Source: $c{$a}{'Source'}\n";
     print 'Type: ' . GetEventType($c{$a}{'EventType'}) . "\n";
     print '-' x 10;
    }

 count
    my $count = $eventlog->count();

   Returns the number of entries loaded from the event log.

FUNCTIONS
 GetEventType
    print 'Event type:' . GetEventType($c{'EventType'}) . "\n";

   Returns a string containing the type of event (Error, Warning,
   Information, Audit Success, Audit Failure, or Unknown).

   GetEventType is exported by default.

CONSTANTS
   Several constants are exported by default. These constants are Event
   Type definitions. They are as follows:

   * EVENT_ERROR (1)
   * EVENT_WARNING (2)
   * EVENT_INFORMATION (4)
   * EVENT_AUDIT_SUCCESS (8)
   * EVENT_AUDIT_FAILURE (16)

RETURN VALUES
   On success, all of the get*Event functions return a hash of the current
   Event. The hash itself has several keys made up of each of the values in
   the Event itself. The following keys are defined (note the capitals):

 TimeGenerated
   The epoch time the event was generated, suitable for feeding to gmtime
   and localtime.

 TimeWritten
   The epoch time the event was written to the event log, usually the same
   as TimeGenerated (give or take a second). Suitable for feeding to gmtime
   and localtime.

 RecordNumber
   The record number of the event. This is assigned and due to the binary
   nature of the file, and can not be expected to be consistant or unique
   on subsequent parsings of the same file.

 EventID
   The event identification number, vendor and application specific.
   Details can often be found in the Microsoft Knowledge Base.

 EventType
   The event type, vendor and application specific.

 Source
   Source of the event, usually the application or service name.

 Computer
   The name of the computer that generated the event.

 SID
   The SID associated with the entry. It is unknown whether this is the SID
   of the source PC, the PC the log was stored on, the user, or something
   else.

 NumStrings
   Number of strings in the event.

 Strings
   An array reference to all (if any) of the strings included with the
   event. Events work a lot like printf format strings, that is, there is a
   fixed message with a variable part, such as:

    The %s service failed to start due to the following error:
    The system cannot find the file specified.

   In this case, the Strings parameter would contain the name of the
   service that would be placed in %s above to complete the event message.

TO DO
   * Support for random access reads.
   * Parsing without loading the whole file into memory. By default, the
   files are only 64k, but it's possible to specify a much larger size.
   * Descriptions for general Microsoft Windows events.
   * Rename/alias getNextEvent and getPreviousEvent to getNewerEvent and
   getOlderEvent?

KNOWN BUGS
   * Occasional spurious Strings are read from the Event Log. It seems the
   log itself specifies they should be there, but there is only garbage
   data to be read.
   * Incomplete parsing. Due to the mysterious nature of the Event Logs and
   the lack of documentation on their format, there are several unknown
   fields in the log. These fields are currently ignored. If anyone knows
   what these fields are for, please let me know.

CAVEATS
   While this module can extract general information on the events, most of
   the error description is stored in system libraries specific to the
   Windows version and patch level that created the log. At this time,
   Parse::EventLog does not have a facility to extract that data.

   Assume the Event Viewer shows the following event description:

    The Print Spooler service was successfully sent a stop control.

   The data to build this description is stored in two locations. The
   first, a DLL file associated with the Service Control Manager, contains
   the string:

    The %s service was successfully sent a %s control.

   The Event Log itself contains the strings:

    Print Spooler

   and

    stop

   Unfortunately, at this time Parse::EventLog is not able to extract the
   string data from files outside of the Event Log itself, only the strings
   contained within it. At this time, I recommend either parsing the events
   on the Windows server itself (via Win32::EventLog or a syslog plugin) or
   manually looking up the data elsewhere.

SEE ALSO
   Win32::EventLog

THANKS
   Thanks to Malik of www.whitehats.ca for the initial data structure
   format that this module was based on. See:
   <http://www.whitehats.ca/main/members/Malik/malik_eventlogs/malik_eventl
   ogs.html> for more details and his origional work.

COPYRIGHT
   Copyright 2005-2006, John Eaglesham

   This module is free software. It may be used, redistributed and/or
   modified under the same terms as Perl itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.