Provided by: swatch_3.2.3-1_all bug

NAME

       swatch - simple watcher

SYNOPSIS

       swatch [ --awk-field-syntax ] [ --config-file|-c file ] [ --daemon ] [
       --extra-include-dir|-I path ] [ --extra-module|-M module_name ] [ --help|-h ] [
       --input-record-separator regex ] [ --old-style-config|-O ] [ --pid-file file ] [
       --restart-time|-r time ] [ --script-dir path ] [ --tail-args arguments_for_tail_program ]
       [ --tail-program-name filename ] [ --version|-V ] [ --use-cpan-file-tail ] [ [
       --examine|-f file_to_examine ] | [ --read-pipe|-p program_to_pipe_from ] | [
       --tail-file|-t file_to_tail ] ] [ --debug [ level ] ] [ --dump-script filename ]

DESCRIPTION

       Swatch is designed to monitor system activity.  In order for Swatch to be useful, it
       requires a configuration file which contains pattern(s) to look for and action(s) to
       perform when each pattern is found.

COMMAND LINE OPTIONS

       --awk-field-syntax
           Use this option only if you want to overide regular expression backreferencing in
           favor of awk(1) style field referencing. Included for backward compatability.

       --config-file|-c filename
           Tells swatch where to find its configuration file. The default is ${HOME}/.swatchrc.

       --daemon
           This tells swatch to run in the background and disassociate itself from any terminal.

       --extra-include-dir|-I path
           This tells swatch where to look for custom action modules.

       --extra-module|-M module_name
           This tells swatch what custom action modules to load in.

       --help|-h
           Prints usage information and exits.

       --input-record-separator=regular_expression
           Tells swatch to use regular_expression to delineate the boundary of each input record.
           The default is a carriage return.

       --old-style-config|-O
           This tells swatch that your configuration file is written using the syntax that was
           abandoned back in the 1990's.

       --pid-file file
           Writes the process ID to file. Useful when running in daemon mode.

       --restart-time=[+]hh:mm[am|pm] or -r [+]hh:mm[am|pm]
           Restart at the specified time where hh is hours and mm is minutes.  If the am/pm
           indicator is omitted, then a 24-hour clock is assumed.  If the time is preceded by the
           "+" character, then the restart time will be set to the current time plus the
           specified time and the am/pm indicator will be ignored.

       --script-dir=/path/to/directory
           This switch causes the temporary watcher script to be written to a file in the
           specified directory rather than the user's home directory. It is highly advised that
           you do NOT use directories that are writable by others such as /tmp.

       --tail-args arguments_for_tail_program
           Pass specific options to the tail(1) program.

       --tail-program-name filename
           Runs an alternate tail(1) like program instead of the system default.

       --version or -V
           Prints version information and exits.

       --use-cpan-file-tail
           Use CPAN's File::Tail module to read the log file instead of the tail(1) command.

       You may specify only one of the following options:

       --tail-file=filename or -t filename
           Examine lines of text as they are added to filename.

       --read-pipe=command or -p command
           Examine input piped in from the command.

       --examine=filename or -f filename
           Use filename as the file to examine.  Swatch will do a single pass through the named
           file.

       The following options are purely for debugging purposes, but are documented here for
       completeness:

       --debug[=level]
           Spew out various levels of debugging for swatch developers.

       --dump-script[=filename]
           Instead of running the watcher script after it is generated, it is written to filename
           or to STDOUT.

       If swatch is called with no options, it is the same as typing the command line

               swatch --config-file=~/.swatchrc --tail-file=/var/log/syslog

       or if /var/log/messages exists

               swatch --config-file=~/.swatchrc --tail-file=/var/log/messages

THE CONFIGURATION FILE

       The configuration file is used by the swatch(8) program to determine what types of
       expression patterns to look for and what type of action(s) should be taken when a pattern
       is matched.

       Each line should contain a keyword and a, sometimes optional, value for that keyword. The
       keyword and value are separated by a space or an equal (=) sign.

       watchfor regex

       ignore regex

       echo [modes]
           Echo the matched line. The text mode may be normal, clear, reset, bold underline,
           underscore, blink, reverse, concealed, black, red green, yellow, blue, magenta,
           on_black, on_red, on_green on_yellow, on_blue, on_magenta, on_cyan, on_white. The
           <on_> colors specify a highlighting color. Some modes may not work on some terminals.
           Normal is the default.  For modes changes and additions check perl module
           Term::ANSIColor man page.

       bell [N]
           Echo the matched line, and send a bell N times (default = 1).

       exec command
           Execute command. The command may contain variables which are substituted with fields
           from the matched line. A $N will be replaced by the Nth field in the line. A $_ will
           be replaced by the entire line. Variable $0 will show the name of the executed script.

       mail [addresses=address:address:...][,subject=your_text_here]
           Send mail to address(es) containing the matched lines as they appear (default address
           is the user who is running the program).

           Note that the @ sign in the email addresses must be escaped with a backslash, like
           "user\@example.com".

       pipe command[,keep_open]
           Pipe matched lines into command. Use the keep_open option to force the pipe to stay
           open until a different pipe action is run or until swatch exits.

       write [user:user:...]
           Use write(1) to send matched lines to user(s).

       throttle hours:minutes:seconds,[key=message|regex|<regexE]>
           This action has been depreciated. Use threshold instead For example,

               throttle 15:00,key="foo"

           would look like this

               threshold track_by="foo",type=limit,count=1,seconds=900

       threshold track_by=key, type=<limit|threshold|both, count=number, seconds=number>
           Thresholding can be done for the complete watchfor block and/or for individual
           actions. Add "threshold=on" as an option along with the other threshold options when
           thresholding an individual action.

           track_by
               The value of this should be something that is unique to the watchfor regular
               expression. Tip: enclose unique parts of the regular expression in parentheses,
               then use the sub matches as part of the value (e.g. track_by="$2:$4").

           type
               There are three types of thresholding. They are as follows:

               limit
                   Perform action(s) for the first "count" matches during the time interval
                   specified by "seconds", then ignore events for the rest of the time interval
                   (kind of like throttle)

               threshold
                   Perform action(s) on each match for up to count matches during the time
                   interval specified by seconds

               both
                   Perform actions(s) once per time interval after "count" matches occur, then
                   ignore additional matches during the time interval specified by "seconds"

       continue
           Use this action to cause swatch to continue to try to match other pattern/action
           groups after it is done with the current pattern/action block.

       quit
           Use this action to cause swatch to clean up and quit immediately.

SPECIAL OPTION

       The following may be used as an option for any of the above actions except for throttle
       and threshold.

       when=day_of_week:hour_of_day
           Use this option to specify windows of time and days when the action can be performed.
           For example:

               mail=sysad-pager@somehost.somedomain,when=1-6:8-17

FOR PERL HACKS ONLY

       perlcode [depth] arbitrary_Perl_code
           This permits you to easily insert random Perl code into your swatchrc file.  The
           optional depth value tells swatch how deep into the code to put the perl code.
           (0=outside the main loop, 1=inside the main loop (default), 2=just inside the
           conditional used by the current watchfor statement, and 3=inside the throttle block).

           Its intended use is to permit variable substitution. For example:

               perlcode $syslog="^\w{3}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}.*";

               watchfor /$syslog hostname pppd/>

           but any valid Perl is permitted.  Remember the semicolon, and make judicious use of
           the --dump-script option if you run into trouble.

CONFIGURATION EXAMPLE

       In this example, a line which contains the string "file system full" will be echoed and
       the screen bell will sound.  Also, threshold will use what is matched within the
       parentheses as its key rather than trying to use the log message with its time stamp cut
       out. Multiple instances of the message will not be echoed if they appear within a minute
       of the first one. Instead the following message will be acted upon after the time interval
       has expired.

SEE ALSO

       signal(3), perl(1), perlre(1)

NOTES

       Upon receiving an ALRM or HUP signal swatch will re-read the configuration file and
       restart, except when used with the --daemon command line option where it will simply exit.
       Swatch will terminate gracefully when it receives a QUIT, TERM, or INT signal.

AUTHOR

           E. Todd Atkins
           Todd.Atkins@StanfordAlumni.ORG

AVAILABILITY

       Swatch is a SourceForge project whose project page is at
       http://sourceforge.net/projects/swatch and homepage is at http://swatch.sourceforge.net