SWATCH(1) User Contributed Perl Documentation SWATCH(1)NAMEswatch - simple watcher
SYNOPSISswatch [ --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, bold,
underscore, blink, inverse, black, red, green, yellow, blue,
magenta, cyan, white, black_h, red_h, green_h, yellow_h, blue_h,
magenta_h, cyan_h, and/or white_h. The _h colors specify a
highlighting color. The other colors are assigned to the letters.
Some modes may not work on some terminals. Normal is the default.
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 $0 or $* will be replaced
by the entire line.
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).
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 ALSOsignal(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
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 1350:
You forgot a '=back' before '=head1'
perl v5.18.1 2008-07-01 SWATCH(1)
