cwatch(1)

NAME
cwatch - a simple log file watcher, written in C

SYNOPSIS
cwatch [-c file] [-F re] [-t file] [-p command] [-f file] [-r restart-time] [-v] [--help] [--dump-script] [--pid-file file] [--daemon]

DESCRIPTION
cwatch monitors a system log for interesting information. It attempts to be a clone of the well-known swatch program as much as possible, but without having to drag masses of perl modules into your system. If cwatch catches a HUP or ALRM signal, it will attempt to re-read the configuration file and restart. When cwatch catches a TERM,QUIT or INT signal, it terminates as gracefully as it can.

OPTIONS

-c file
    Use file as the configuration file. If you don't specify a configuration file, cwatch attempts to open $HOME/.cwatchrc and if that fails, it uses the builtin configuration of
    watchfor /.*/
        echo

--help
    Displays usage information, then exits.

-F re
    Log records are separated by re instead of by newlines.

-V  Display the version information, then exit.

-t file
    Examine lines of text as they are added to file. (This is the same as -p cat file)

-p command
    Examine input piped from command.

-f file
    Do a single pass through file.

-r restart-time
    Restart cwatch at the given time. The restart-time may be given as an absolute time in the form HH:MM[am|pm], which means that cwatch will restart every day at the specified time, or it may be a delay in the form HH:MM, which means that cwatch will restart every HH:MM after you start it.

--dump-script
    For debugging only. Display the (parsed) contents of the configuration file, then exit.

If cwatch is called without any input option, it defaults to -t /var/log/syslog.

--daemon
    When this option is given, cwatch will exit when it receives a SIGHUP or SIGALRM signal. (This means that the -r option will not work with --daemon.)

--pid-file file
    Write the process id of the supervisor process to file as a human-readable string suitable for passing as an argument to a program (like, oh, kill -HUP `cat file`)

THE CONFIGURATION FILE
cwatch attempts to closely follow the format of the swatch (v3) configuration file, with some differences having to do with how it parses the configuration files. A configuration file is made up of a series of patterns with actions associated with them. The patterns are either

watchfor regex
    If the pattern is seen, do the associated actions.

ignore regex
    If the pattern is seen, do nothing with it.

Unlike swatch, cwatch only accepts a single pattern regex per pattern, so common swatch expressions like
ignore /foo/,/bar/,/fu/
are isallowed; you need to rewrite them as
ignore /foo|bar|fu/
watchfor patterns take a collection of actions (quoted strings MUST be quoted with double-quotes, unlike swatch, where text can be tossed in any old way.)

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.

bell [N]
    Ring the terminal bell N(default=1) times.

exec
    Execute command. The command may contain variables which are substituted with fields from the matched line. A $N will be replaced by the Nth filed in the line. A $0 or $* will be replaced by the entire line.

mail [addresses=to:to:...][,subject=text]
    Send mail to address(es) containing the matched lines as they appear. If you don't give addresses to mail the letter to, it will be sent to the user who is running the program.) pipe Pipe matched lines into command. keep_open forces the pipe to stay open until a different pipe action is run or until swatch exits.

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

throttle hours:minutes:seconds [,use=message|regex]
    Limit the number of times that the matched pattern has actions performed on it. Once a command is throttled, nothing except continue takes effect until after the delay given. The use= option is either regex, which means that the throttling continues until some other waitfor pattern is matched, or message, which means that the throttling continues until the pattern matches a string that's different from the one it originally matched.

continue
    Causes cwatch to match other patterns after it is done with the current one.

quit
    cwatch cleans up and exits.

All of these options except quit also take the when argument;

when=days:hours
    Only perform the action on the specified days and hours. for example bell 10 when=1-5:4 means that the bell command only runs at teatime on weekdays.

BUGS
The echo modes are not yet implemented.

AUTHOR
David Parsons <orc@pell.chi.il.us>

SEE ALSO
syslog.conf(5), syslogd(8).