SWATCH(1)

NAME
swatch - simple watcher

SYNOPSIS
swatch [ --config-file file ] [ --restart-time time ] [ --input-record-separator regex ] [ [ --examine file_to_examine ] | [ --read-pipe program_to_pipe_from ] | [ --tail file_to_tail ] ] [ --daemon ]

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
Tells swatch where to find its configuration file. The default is ${HOME}/.swatchrc. Prints usage informatiion and exits. Tells swatch to use regular_expression to delineate the boundary of each input record. The default is a carriage return. Restart after 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 preceeded 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. 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. Prints version information and exits.

You may specify only one of the following options: Examine lines of text as they are added to filename. Examine input piped in from the command. 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: 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 Linux)

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

If the configuration file doesn't exist then the following configuration is used:

        watchfor  /.*/
            echo modes=random

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 space or an equal (=) sign.

watchfor regex

ignore regex 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. Echo the matched line, and send a bell N times (default = 1). 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. Send mail to address(es) containing the matched lines as they appear (default address is the user who is running the program). 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. Use write(1) to send matched lines to user(s). Use this action to limit the number of times that the matched pattern has actions performed on it.

The use=regex option will cause throttling to be based on the regular expression instead of the message (use=message is the default). 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. 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 Use this option to specify windows of time and days when the action can be performed. For example:

CONFIGURATION EXAMPLE
watchfor /file system full/
    echo
    bell
    throttle 01:00

This example a line which contains the string "file system full" will be echoed and the screen bell will sound. Also, 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. This is what may appear if a the message appeared 20 times. `** 20 in 00:01:00 ==' host.domain: /var: file system full>

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

NOTES
Upon receiving a ALRM or HUP signal swatch will re-read the configuration file and restart. Swatch will terminate gracefully when it receives a QUIT, TERM, or INT signal.

AUTHOR
    E. Todd Atkins
    eta@engr.ucsb.edu
    Engineering Computing Infrastructure
    School of Engineering
    University of California, Santa Barbara

AVAILABILITY
The official FTP location is ftp://ftp.stanford.edu/general/security-tools/swatch Latest release is available at http://www.engr.ucsb.edu/~eta/swatch/latest.tar Swatch's homepage is http://www.engr.ucsb.edu/~eta/swatch or http://www.stanford.edu/~atkins/swatch