--config-file=filename or -c filename

Tells swatch where to find its configuration file. The default is ${HOME}/.swatchrc.

--help

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.

--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 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.

--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.

--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:

--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"

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

        watchfor  /.*/
            echo

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 [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,[use=message|regex|<regex]>

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.

You can also specify a perl compliant regular expression as the value for B,use>. The default is use=``^\w{3}\s+\d{1,2}\s\d{2}:\d{2}:\d{2}\s+(.*)'' causes the key to be the syslog message without the timestamp. This is most useful when throttling non-syslog created files.

threshold events:seconds,[repeat=no|yes]

This action limits the actions on a matched pattern based on the number of times it appears in a given time frame. An action like ``threshold 4:60'' will not perform any actions on that pattern unless it appears 4 times within any 60 second period (4:60 is the arbitrary default value).

The repeat=no option will prevent the timer from being reset after the threshold has been reached. By default (repeat=yes), once the pattern has been triggered, a new 60 second period is begun, which means that if the patterns match quickly enough, a threshold of 4:60 could mean that 1 in every 4 messages is reported. By using repeat=no, you indicate that there is not to be more than one match every time interval.

Note that this is similar to, but different from, the standard ``throttle'' command, since ``throttle'' shows the first line and ignores the rest, while ``threshold'' shows the last line and ignores the preceeding (and optionally the following). However, an action like ``threshold 1:120'' should perform similarly to ``throttle 0:2:0,use=regex'' and has the advantage of not relying on a particular timestamp format in the source log entry.

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.

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 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 through use like.

"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/ echo bell throttle 01:00,use=$fsf_regex

In this example, a line which contains the string ``file system full'' will be echoed and the screen bell will sound. Also, throttle 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. This is what may appear if the message appeared 20 times.

*

"** 20 in 00:01:00 ==" host.domain: /var: file system full>