cislog-report.pl - summarize Cisco Systems device log messages

Copyright (C) 2002-2004 John Kristoff

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.

Obtaining the Latest Release

  For the latest version of this software visit the following page:

    John Kristoff's Home Page, Northwestern University
    <http://aharp.ittns.northwestern.edu/software/>

Getting Started

  This program is a rudimentary Cisco Systems device log summarizing
  tool.  This program expects a Cisco formatted log file as a command
  line argument or as standard input (STDIN) to the program.

  Example:

    ./cislog-report.pl /path/to/cisco/logfile

     or

    ./cislog-report.pl < /path/to/cisco/logfile

    or

    STDOUT | ./cislog-report.pl

Requirements

  This program assumes a unix-based system.  It was tested on Linux and
  OpenBSD, but it should run on other platforms equally as well.  Version
  5.6.1 of the Perl programming language was used on the test platform
  and it is expected that similar or newer versions of Perl will also work.

  Log input is based on a various Cisco IOS and CatOS generated log files.
  Similar or other cisco devices may also work.

Reporting Details

  This program analyzes cisco log messages on a line by line basis.
  Each line is parsed and categorized according to its log message
  detail.  At this time, the following log message types are known
  and summarized by this program:

    traceback        - Trackback/Process critical messages
    malloc failures  - System memory allocation failures
    CPU hog          - CPU hog messages
    device logins    - Logins permitted and denied
    configurations   - device configurations
    ACL hits         - various ACL counters
    OSPF changes     - OSPF adjaceny changes
    rshell attemps   - RSHELL command attempts
    link changes     - various link status changes and messages
    port security    - PORT security violations
    multicast        - various multicast messages

  For further details on how the log messages are summarized examine
  the program code.  Log messages not understood by this program are
  placed in an unknown category and can be displayed if DEBUG mode is
  enabled.  DEBUG mode may be useful to help build new parsing routines
  for unknown messages or to assist in the troubleshooting process by
  displaying unusual log messages in full.

Configuration

  This program should generally work without any customized options
  for a particular environment.  However, the output generated by the
  program can be somewhat controlled by a small number of variables
  that are defined within the beginning portion of the code.  The
  following options are available:

    DEBUG             Generates additional output to aid troubleshooting.
		      This option is particularly useful for displaying
		      log messages the program does not currently
		      understand.

		      Setting: [0|1]  (0 = disabled, 1 = enabled)
		      Default: disabled 

    RESOLVE           Controls whether the program attempts to display
		      the host names of IP addresses found in the log
		      messages and output in the reports.  Enabling this
		      option slows down the program considerably, because
		      execution time then depends on the program being
		      able to do DNS queries.  In some cases, IP addresses
		      may not have associated names, which will cause a
		      considerable delay in program execution time since
		      a timeout must occur before the program can continue.
		      The program will output '[lookup failed]' in place of
		      a host name when an IP address cannot be resolved.

		      Setting: [0|1]  (0 = disabled, 1 = enabled)
		      Default: enabled

     TOPx             Determines how many rows of summary to include in
                      the reports for each category of log message.

                      Setting: [5 to 25 recommended]
                      Default: 10

References

  This program was designed to provide a 'quick-n-dirty' summary view
  of log messages various cisco devices were generating.  Other log
  reporting tools are available and may be more appropriate for more
  demanding requirements.  The following references may be useful for
  exploring the use of other tools and techniques:

    Lire - open source reporting and analysis software
    <http://www.logreport.org>
    GNU GPL software that manages many types of system log file formats
    including DNS, HTTP, FTP, firewalls, email and more.  A very complete
    system written mostly with the Perl programming language and using
    XML formats.

    Log Analysis Resources page - long list of tools and info 
    <http://www.loganalysis.org>
    A web page maintained by Tina Bird and Marcus Ranum that contains
    a large collection of links to log management information and tools.

    Cisco-centric Open Source Community - various cisco tools
    <http://cosi-nms.sourceforge.net>
    A portal for developers and tools for managing cisco devices.

Caveats

  This program may not run properly on your systems.  While it is not
  expected to cause harm in its usage, correct operation and report
  output may not be possible depending on system configuration.  It
  has been verified by one other party in limited testing to perform as
  expected, but mileage may vary. It is recommended that precautions
  be taken, such as running this script first on a test system with a
  copy of typical named log data for the environment.

Contact Information

  John Kristoff <jtk@northwestern.edu>
  Northwestern University
  2001 Sheridan Road
  Evanston, IL USA
                                                                                
  Personal and work webpage: <http://aharp.ittns.northwestern.edu>

Revision History

  2003-07-24,jtk - Initial program release
  2004-06-16,jtk - Packaged up new version for distribution
                   minor updates made months ago, see code for details
