.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SWATCHDOG 1p"
.TH SWATCHDOG 1p "2023-01-20" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
swatchdog \- simple watcher
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBswatchdog\fR 
[ \fB\-\-awk\-field\-syntax\fR ]
[ \fB\-\-config\-file|\-c\fR \fIfile\fR ] 
[ \fB\-\-daemon\fR ] 
[ \fB\-\-extra\-include\-dir|\-I\fR \fIpath\fR ]
[ \fB\-\-extra\-module|\-M\fR \fImodule_name\fR ]
[ \fB\-\-help|\-h\fR ]
[ \fB\-\-input\-record\-separator\fR \fIregex\fR ] 
[ \fB\-\-old\-style\-config|\-O\fR ]
[ \fB\-\-pid\-file\fR \fIfile\fR ]
[ \fB\-\-restart\-time|\-r\fR \fItime\fR ] 
[ \fB\-\-script\-dir\fR \fIpath\fR ]
[ \fB\-\-tail\-args\fR \fIarguments_for_tail_program\fR ]
[ \fB\-\-tail\-program\-name\fR \fIfilename\fR ]
[ \fB\-\-version|\-V\fR ]
[ \fB\-\-use\-cpan\-file\-tail\fR ]
[ [ \fB\-\-examine|\-f\fR \fIfile_to_examine\fR ] 
| [ \fB\-\-read\-pipe|\-p\fR \fIprogram_to_pipe_from\fR ] 
| [ \fB\-\-tail\-file|\-t\fR \fIfile_to_tail\fR ] ]
[ \fB\-\-debug\fR [ \fIlevel\fR ] ] 
[ \fB\-\-dump\-script\fR \fIfilename\fR ]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBSwatchdog\fR is designed to monitor system activity.
In order for \fBSwatchdog\fR to be useful, it requires a configuration file
which contains \fIpattern(s)\fR to look for and \fIaction(s)\fR
to perform when each pattern is found.
.SH "COMMAND LINE OPTIONS"
.IX Header "COMMAND LINE OPTIONS"
.IP "\fB\-\-awk\-field\-syntax\fR" 4
.IX Item "--awk-field-syntax"
Use this option only if you want to override regular expression backreferencing
in favor of \fB\fBawk\fB\|(1)\fR style field referencing. Included for backward 
compatibility.
.IP "\fB\-\-config\-file|\-c\fR \fIfilename\fR" 4
.IX Item "--config-file|-c filename"
Tells \fBswatchdog\fR where to find its configuration file. The default
is \fI${\s-1HOME\s0}/.swatchdogrc\fR.
.IP "\fB\-\-daemon\fR" 4
.IX Item "--daemon"
This tells \fBswatchdog\fR to run in the background and disassociate itself from 
any terminal.
.IP "\fB\-\-extra\-include\-dir|\-I\fR \fIpath\fR" 4
.IX Item "--extra-include-dir|-I path"
This tells \fBswatchdog\fR where to look for custom \fIaction\fR modules.
.IP "\fB\-\-extra\-module|\-M\fR \fImodule_name\fR" 4
.IX Item "--extra-module|-M module_name"
This tells \fBswatchdog\fR what custom \fIaction\fR modules to load in.
.IP "\fB\-\-help|\-h\fR" 4
.IX Item "--help|-h"
Prints usage information and exits.
.IP "\fB\-\-input\-record\-separator\fR=\fIregular_expression\fR" 4
.IX Item "--input-record-separator=regular_expression"
Tells \fBswatchdog\fR to use \fIregular_expression\fR to delineate
the boundary of each input record. The default is a carriage return.
.IP "\fB\-\-old\-style\-config|\-O\fR" 4
.IX Item "--old-style-config|-O"
This tells \fBswatchdog\fR that your configuration file is written using the
syntax that was abandoned back in the 1990's.
.IP "\fB\-\-pid\-file\fR \fIfile\fR" 4
.IX Item "--pid-file file"
Writes the process \s-1ID\s0 to \fIfile\fR. Useful when running in daemon mode.
.IP "\fB\-\-restart\-time\fR=\fI[+]hh:mm[am|pm]\fR or \fB\-r\fR \fI[+]hh:mm[am|pm]\fR" 4
.IX Item "--restart-time=[+]hh:mm[am|pm] or -r [+]hh:mm[am|pm]"
Restart at the specified time where \fIhh\fR is hours and \fImm\fR is minutes. 
If the am/pm indicator is omitted, then a 24\-hour clock is assumed. 
If the time is preceded by the \*(L"+\*(R" character, then the restart time 
will be set to the current time plus the specified time and the am/pm
indicator will be ignored.
.IP "\fB\-\-script\-dir\fR=\fI/path/to/directory\fR" 4
.IX Item "--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 \fB\s-1NOT\s0\fR use directories that are writable by others
such as /tmp.
.IP "\fB\-\-tail\-args\fR \fIarguments_for_tail_program\fR" 4
.IX Item "--tail-args arguments_for_tail_program"
Pass specific options to the \fB\fBtail\fB\|(1)\fR program.
.IP "\fB\-\-tail\-program\-name\fR \fIfilename\fR" 4
.IX Item "--tail-program-name filename"
Runs an alternate \fB\fBtail\fB\|(1)\fR like program instead of the system default.
.IP "\fB\-\-version\fR or \fB\-V\fR" 4
.IX Item "--version or -V"
Prints version information and exits.
.IP "\fB\-\-use\-cpan\-file\-tail\fR" 4
.IX Item "--use-cpan-file-tail"
Use \s-1CPAN\s0's File::Tail module to read the log file instead of the \fBtail\fR\|(1) 
command.
.PP
You may specify only one of the following options:
.IP "\fB\-\-tail\-file\fR=\fIfilename\fR or \fB\-t\fR \fIfilename\fR" 4
.IX Item "--tail-file=filename or -t filename"
Examine lines of text as they are added to filename.
.IP "\fB\-\-read\-pipe\fR=\fIcommand\fR or \fB\-p\fR \fIcommand\fR" 4
.IX Item "--read-pipe=command or -p command"
Examine input piped in from the \fIcommand\fR.
.IP "\fB\-\-examine\fR=\fIfilename\fR or \fB\-f\fR \fIfilename\fR" 4
.IX Item "--examine=filename or -f filename"
Use \fIfilename\fR as the file to examine. 
\&\fBSwatchdog\fR will do a single pass through the named file.
.PP
The following options are purely for debugging purposes, but are
documented here for completeness:
.IP "\fB\-\-debug\fR[=\fIlevel\fR]" 4
.IX Item "--debug[=level]"
Spew out various levels of debugging for swatchdog developers.
.IP "\fB\-\-dump\-script\fR[=\fIfilename\fR]" 4
.IX Item "--dump-script[=filename]"
Instead of running the watcher script after it is generated, 
it is written to \fIfilename\fR or to \s-1STDOUT.\s0
.PP
If swatchdog is called with no options, it is the same as typing the 
command line
.PP
.Vb 1
\&        swatchdog \-\-config\-file=~/.swatchdogrc \-\-tail\-file=/var/log/syslog
.Ve
.PP
or if /var/log/messages exists
.PP
.Vb 1
\&        swatchdog \-\-config\-file=~/.swatchdogrc \-\-tail\-file=/var/log/messages
.Ve
.SH "THE CONFIGURATION FILE"
.IX Header "THE CONFIGURATION FILE"
The configuration file is used by the \fB\fBswatchdog\fB\|(8)\fR
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.
.PP
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.
.PP
watchfor regex
.PP
ignore regex
.IP "\fBecho [modes]\fR" 4
.IX Item "echo [modes]"
Echo the matched line. The text mode may be \fInormal\fR, \fIclear\fR, \fIreset\fR, \fIbold\fR
\&\fIunderline\fR, \fIunderscore\fR, \fIblink\fR, \fIreverse\fR, \fIconcealed\fR, \fIblack\fR, \fIred\fR
\&\fIgreen\fR, \fIyellow\fR, \fIblue\fR, \fImagenta\fR, \fIon_black\fR, \fIon_red\fR, \fIon_green\fR
\&\fIon_yellow\fR, \fIon_blue\fR, \fIon_magenta\fR, \fIon_cyan\fR, \fIon_white\fR. The <on_> colors
specify a highlighting color. Some modes may not work on some terminals. \fBNormal\fR
is the default.
For \fBmodes\fR changes and additions check perl module Term::ANSIColor man page.
.IP "\fBbell [N]\fR" 4
.IX Item "bell [N]"
Echo the matched line, and send a bell \fIN\fR times (default = 1).
.IP "\fBexec command\fR" 4
.IX Item "exec command"
Execute \fIcommand\fR. The \fIcommand\fR may contain variables which are 
substituted with fields from the matched line. If the \fB\-\-awk\-field\-syntax\fR
command-line option has been specified, then each \fI\f(CI$N\fI\fR will be replaced
by the \fINth\fR field in the line. If the option has not been specified,
then each \fI\f(CI$N\fI\fR will refer to a backreference in the regular expression
used to match the line.
.Sp
A \fI\f(CI$0\fI\fR or \fI$*\fR will always be replaced by the entire line, unless they
have been escaped, regardless of the \fB\-\-awk\-field\-syntax\fR option.
.Sp
An escaped \fI\f(CI$N\fI\fR, \fI\f(CI$0\fI\fR or \fI$*\fR may have unwanted effects since the value
will be determined by the shell used to execute the command.
.IP "\fBmail [addresses=address:address:...][,subject=your_text_here]\fR" 4
.IX Item "mail [addresses=address:address:...][,subject=your_text_here]"
Send \fImail\fR to \fIaddress(es)\fR containing the matched lines as
they appear (default address is the user who is running the program).
.IP "\fBpipe command[,keep_open]\fR" 4
.IX Item "pipe command[,keep_open]"
Pipe matched lines into \fIcommand\fR. Use the \fBkeep_open\fR option to 
force the pipe to stay open until a different pipe action is run or 
until swatchdog exits.
.IP "\fBwrite [user:user:...]\fR" 4
.IX Item "write [user:user:...]"
Use \fB\fBwrite\fB\|(1)\fR to send matched lines to \fIuser(s)\fR.
.IP "\fBthrottle hours:minutes:seconds,[key=message|regex|<regexE\fR]>" 4
.IX Item "throttle hours:minutes:seconds,[key=message|regex|<regexE]>"
This action has been depreciated. Use \fBthreshold\fR instead
For example,
.RS 4
.Sp
.RS 4
throttle 15:00,key=\*(L"foo\*(R"
.RE
.RE
.RS 4
.Sp
would look like this
.Sp
.RS 4
threshold track_by=\*(L"foo\*(R",type=limit,count=1,seconds=900
.RE
.RE
.RS 4
.RE
.IP "\fBthreshold track_by=key, type=<limit|threshold|both\fR, count=number, seconds=number>" 4
.IX Item "threshold track_by=key, type=<limit|threshold|both, count=number, seconds=number>"
Thresholding can be done for the complete \fBwatchfor\fR block and/or for
individual actions. Add \*(L"threshold=on\*(R" as an option along with the other
threshold options when thresholding an individual action.
.RS 4
.IP "\fBtrack_by\fR" 4
.IX Item "track_by"
The value of this should be something that is unique to the \fBwatchfor\fR
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=\*(L"$2:$4\*(R").
.IP "\fBtype\fR" 4
.IX Item "type"
There are three types of thresholding. They are as follows:
.RS 4
.IP "\fBlimit\fR" 4
.IX Item "limit"
Perform action(s) for the first "\fBcount\fR\*(L" matches during the
time interval specified by \*(R"\fBseconds\fR",
then ignore events for the rest of the time interval (kind of like throttle)
.IP "\fBthreshold\fR" 4
.IX Item "threshold"
Perform action(s) on each match for up to \fBcount\fR matches during the 
time interval specified by \fBseconds\fR
.IP "\fBboth\fR" 4
.IX Item "both"
Perform actions(s) once per time interval after "\fBcount\fR\*(L" matches occur,
then ignore additional matches during the time interval 
specified by \*(R"\fBseconds\fR"
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.IP "\fBcontinue\fR" 4
.IX Item "continue"
Use this action to cause \fBswatchdog\fR to continue to try to match other
pattern/action groups after it is done with the current pattern/action
block.
.IP "\fBquit\fR" 4
.IX Item "quit"
Use this action to cause \fBswatchdog\fR to clean up and quit immediately.
.SH "SPECIAL OPTION"
.IX Header "SPECIAL OPTION"
The following may be used as an option for any of the above actions except for throttle and threshold.
.IP "\fBwhen=\fR\fIday_of_week:hour_of_day\fR" 4
.IX Item "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:
.RS 4
.Sp
.RS 4
mail=sysad\-pager@somehost.somedomain,when=1\-6:8\-17
.RE
.RE
.RS 4
.RE
.SH "FOR PERL HACKS ONLY"
.IX Header "FOR PERL HACKS ONLY"
.IP "\fBperlcode\fR [\fIdepth\fR] arbitrary_Perl_code" 4
.IX Item "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).
.Sp
Its intended use is to permit variable substitution. For example:
.RS 4
.Sp
.RS 4
perlcode \f(CW$syslog\fR=\*(L"^\ew{3}\es+\ed{1,2}\es+\ed{2}:\ed{2}:\ed{2}.*\*(R";
.Sp
watchfor /$syslog hostname pppd/>
.RE
.RE
.RS 4
.Sp
but any valid Perl is permitted.  Remember the semicolon, and make judicious
use of the \fB\-\-dump\-script\fR option if you run into trouble.
.RE
.SH "CONFIGURATION EXAMPLE"
.IX Header "CONFIGURATION EXAMPLE"
.RS 4
perlcode my \f(CW$fsf_regex\fR = '\ed{2}:\ed{2}:\ed{2}\es+(.* file system full)';
.Sp
watchfor /$fsf_regex/
    threshold track_by=$1,type=limit,count=1,seconds=60
    echo
    bell
.RE
.PP
In this example, a line which contains the string \*(L"file system full\*(R" will
be echoed and the screen bell will sound.  Also, \fBthreshold\fR 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fB\fBsignal\fB\|(3)\fR, \fB\fBperl\fB\|(1)\fR, \fB\fBperlre\fB\|(1)\fR
.SH "NOTES"
.IX Header "NOTES"
Upon receiving an \s-1ALRM\s0 or \s-1HUP\s0 signal swatchdog will re-read the
configuration file and restart, except when used with the \fI\-\-daemon\fR 
command line option where it will simply exit.
Swatchdog will terminate gracefully
when it receives a \s-1QUIT, TERM,\s0 or \s-1INT\s0 signal.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 2
\&    E. Todd Atkins
\&    Todd.Atkins@StanfordAlumni.ORG
.Ve
.SH "AVAILABILITY"
.IX Header "AVAILABILITY"
Swatchdog is a SourceForge project whose project page is at 
http://sourceforge.net/projects/swatchdog and homepage is at
http://swatchdog.sourceforge.net