swatchdog - simple watcher
swatchdog [ --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 ]
Swatchdog is designed to monitor system activity. In order
for Swatchdog 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.
- --awk-field-syntax
- Use this option only if you want to override regular expression
backreferencing in favor of awk(1) style field
referencing. Included for backward compatibility.
- --config-file|-c
filename
- Tells swatchdog where to find its configuration file. The default
is ${HOME}/.swatchdogrc.
- --daemon
- This tells swatchdog to run in the background and disassociate
itself from any terminal.
- This tells swatchdog where to look for custom action
modules.
- This tells swatchdog what custom action modules to load
in.
- --help|-h
- Prints usage information and exits.
- --input-record-separator=regular_expression
- Tells swatchdog to use regular_expression to delineate the
boundary of each input record. The default is a carriage return.
- --old-style-config|-O
- This tells swatchdog 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. Swatchdog 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 swatchdog developers.
- --dump-script[=filename]
- Instead of running the watcher script after it is generated, it is written
to filename or to STDOUT.
If swatchdog is called with no options, it is the same as typing
the command line
swatchdog --config-file=~/.swatchdogrc --tail-file=/var/log/syslog
or if /var/log/messages exists
swatchdog --config-file=~/.swatchdogrc --tail-file=/var/log/messages
The configuration file is used by the
swatchdog(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. If the
--awk-field-syntax command-line option has been specified, then
each $N will be replaced by
the Nth field in the line. If the option has not been specified,
then each $N will refer to a
backreference in the regular expression used to match the line.
A $0 or $*
will always be replaced by the entire line, unless they have been
escaped, regardless of the --awk-field-syntax option.
An escaped $N,
$0 or $* may have
unwanted effects since the value will be determined by the shell used to
execute the command.
- 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
swatchdog 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,
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 swatchdog 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 swatchdog to clean up and quit
immediately.
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
- perlcode
[depth] arbitrary_Perl_code
- This permits you to easily insert random Perl code into your swatchdogrc
file. The optional depth value tells swatchdog 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.
perlcode my
$fsf_regex =
'\d{2}:\d{2}:\d{2}\s+(.* file system full)';
watchfor /$fsf_regex/
threshold track_by=$1,type=limit,count=1,seconds=60
echo
bell
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.
signal(3), perl(1),
perlre(1)
Upon receiving an ALRM or HUP signal swatchdog will re-read the
configuration file and restart, except when used with the --daemon
command line option where it will simply exit. Swatchdog will terminate
gracefully when it receives a QUIT, TERM, or INT signal.
E. Todd Atkins
Todd.Atkins@StanfordAlumni.ORG
Swatchdog is a SourceForge project whose project page is at
http://sourceforge.net/projects/swatchdog and homepage is at
http://swatchdog.sourceforge.net