PageRenderTime 25ms CodeModel.GetById 21ms app.highlight 1ms RepoModel.GetById 1ms app.codeStats 0ms

/swatch-3.2.3/README

#
#! | 123 lines | 89 code | 34 blank | 0 comment | 0 complexity | f64fecd22f4982895b019e89eeabc797 MD5 | raw file
  1
  2Thank you for your interest in swatch: the Simple WATCHdog.
  3
  4Swatch is a SourceForge project whose project page is at 
  5http://sourceforge.net/projects/swatch and homepage is at
  6http://swatch.sourceforge.net
  7
  8Swatch was originally written to actively monitor messages as
  9they are written to a log file via the UNIX syslog utility. For
 10a simple demonstration type "perl swatch --examine=FILENAME" with
 11FILENAME being the file that you would like to see the contents of.
 12All this example will do is demonstrate the different text modes
 13that are available with to the echo action.
 14
 15Read the INSTALL file for installation instructions.
 16
 17IF YOU ENCOUNTER A BUG...
 18
 19Please send mail to todd.atkins@stanfordalumni.org about it, but first make
 20sure that it is not mentioned in the KNOWN_BUGS file and that you are 
 21using the latest release.
 22
 23MAJOR CHANGES IN VERSION 3.1
 24 
 25  Added --extra-include-dirs (or -I) and --extra-modules (or -M) command
 26  line options. This allows one to extend the functionality of swatch by
 27  defining customized actions. See the modules in the "examples" directory
 28  to see how this feature can be used.
 29
 30  Changed "-I" command option from being shorthand for 
 31  "--input-record-separator" to being short for "--extra-include-dirs"
 32  in order to be more consistent with perl's command line arguments. 
 33
 34  Added --tail-program-name and --tail-args command line options. This 
 35  allows one to use more robust tail commands like GNU tail. Here is
 36  how I use it to watch multiple files and not have to worry when they
 37  get rotated:
 38
 39    % swatch --tail-prog=/usr/local/bin/gtail \
 40             --tail-args '--follow=name --lines=1' \
 41             --tail-file="/var/log/messages /var/log/snort/alert"
 42
 43  Added possibility for user to overide "message" option to any action.
 44  Changed default tail arguments from "-1 -f" to "-n 0 -f"
 45
 46  Put action and throttle code into modules named Swatch::Actions and
 47  Swatch::Throttle respectively.
 48
 49  Added --awk-field-syntax and --noawk-field-syntax command line options
 50  with --noawk-field-syntax now set as the default
 51
 52  Added option for user to use their own regular expression to extract a 
 53  throttle key from a message using greedy pattern matching.
 54
 55  Went back to using the system's tail(1) command for tailing files due
 56  to all of the problems that folks were experiencing with the File::Tail
 57  CPAN module.
 58
 59  Added --use-cpan-file-tail option to users to keep using the File::Tail
 60  module for tailing files.
 61
 62  Added perlcode to configuration file. This allows for perl hackers to 
 63  make use of variables in their configuration files. There is a depth 
 64  setting which allows the perlcode to be placed in different levels of 
 65  the nested blocks that are used in the watcher script.  Here is how
 66  one could use it to define generic regular expressions for matching 
 67  and defining fields for different styles of log file lines:
 68
 69    # matches Snort pre-processor short alerts
 70    perlcode my $spp_regex = '\[\*\*\]\s+(\[\d+:\d+:\d+\])\s+([^:]*):.*from (\d+\.\d+\.\d+\.\d+)(.*)$';
 71    # matches short Snort alerts ($1 = alert message, $2 = src IP)
 72    perlcode my $snort_regex = '\[\*\*\]\s+(.*)\s+\[\*\*\].*\{\w+\} (\d+\.\d+\.\d+\.\d+)';
 73    # matches syslog lines ($1 set to everything after the timestamp)
 74    perlcode my $syslog_regex = '^\w{3}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}.*:(.*)';
 75
 76    # report every type of snort alert but throttle them
 77    watchfor /.*/ and /$snort_regex/
 78	throttle 5:00,key=$1 $2
 79        echo modes=green
 80
 81    # report every type of syslog message but throttle them
 82    watchfor /.*/ and /$syslog_regex/
 83	throttle 5:00,key=$1
 84        echo modes=green
 85
 86OTHER MAJOR CHANGES SINCE VERSION 2.X
 87
 88The configuration file now has a completely different format. You can still
 89use your old configuration files if you use the "--old-style-config" switch
 90if you insist.
 91
 92I have re-written most a lot of the code to take advantage of features
 93and modules that were made available with perl 5. 
 94
 95It now requires perl 5 and the following modules: Time::HiRes, Date::Calc, 
 96Date::Format, Date::Manip, Term::ANSIColor, File::Tail.
 97
 98I have added the seven colors that color xterminals recognize to the echo
 99action.
100
101The manual is now embedded into the script in POD format. Use pod2text, 
102pod2html, or your favorite pod2* program to create a more easily readable
103document.
104
105FUTURE DIRECTIONS
106
107I am working on a thresholding module that will behave in a manner that is 
108similar to thresholding in the Snort IDS (www.snort.org). This should 
109eventually replace the current throttling mechanism.
110
111SUGGESTIONS?
112
113Please mail suggestions, problems, and/or complaints about swatch
114to Todd.Atkins@StanfordAlumni.ORG
115
116DONATIONS?
117
118The swatch program is provided to you free of charge. However, if you find
119it useful I encourage you to send in a donation toward its continuous 
120development.  Please send donations online via PayPal (www.paypal.com) using   
121my todd.atkins@stanfordalumni.org address
122
123Thank you.