1SWATCHDOG(1) User Contributed Perl Documentation SWATCHDOG(1)
2
6 swatchdog - simple watcher
7
9 swatchdog [ --awk-field-syntax ] [ --config-file|-c file ] [ --daemon ]
10 [ --extra-include-dir|-I path ] [ --extra-module|-M module_name ] [
11 --help|-h ] [ --input-record-separator regex ] [ --old-style-config|-O
12 ] [ --pid-file file ] [ --restart-time|-r time ] [ --script-dir path ]
13 [ --tail-args arguments_for_tail_program ] [ --tail-program-name
14 filename ] [ --version|-V ] [ --use-cpan-file-tail ] [ [ --examine|-f
15 file_to_examine ] | [ --read-pipe|-p program_to_pipe_from ] | [
16 --tail-file|-t file_to_tail ] ] [ --debug [ level ] ] [ --dump-script
17 filename ]
18
20 Swatchdog is designed to monitor system activity. In order for
21 Swatchdog to be useful, it requires a configuration file which contains
22 pattern(s) to look for and action(s) to perform when each pattern is
23 found.
24
26 --awk-field-syntax
27 Use this option only if you want to overide regular expression
28 backreferencing in favor of awk(1) style field referencing.
29 Included for backward compatibility.
30 --config-file|-c filename
32 Tells swatchdog where to find its configuration file. The default
33 is ${HOME}/.swatchdogrc.
34 --daemon
36 This tells swatchdog to run in the background and disassociate
37 itself from any terminal.
38 --extra-include-dir|-I path
40 This tells swatchdog where to look for custom action modules.
41 --extra-module|-M module_name
43 This tells swatchdog what custom action modules to load in.
44 --help|-h
46 Prints usage information and exits.
47 --input-record-separator=regular_expression
49 Tells swatchdog to use regular_expression to delineate the boundary
50 of each input record. The default is a carriage return.
51 --old-style-config|-O
53 This tells swatchdog that your configuration file is written using
54 the syntax that was abandoned back in the 1990's.
55 --pid-file file
57 Writes the process ID to file. Useful when running in daemon mode.
58 --restart-time=[+]hh:mm[am|pm] or -r [+]hh:mm[am|pm]
60 Restart at the specified time where hh is hours and mm is minutes.
61 If the am/pm indicator is omitted, then a 24-hour clock is assumed.
62 If the time is preceded by the "+" character, then the restart time
63 will be set to the current time plus the specified time and the
64 am/pm indicator will be ignored.
65 --script-dir=/path/to/directory
67 This switch causes the temporary watcher script to be written to a
68 file in the specified directory rather than the user's home
69 directory. It is highly advised that you do NOT use directories
70 that are writable by others such as /tmp.
71 --tail-args arguments_for_tail_program
73 Pass specific options to the tail(1) program.
74 --tail-program-name filename
76 Runs an alternate tail(1) like program instead of the system
77 default.
78 --version or -V
80 Prints version information and exits.
81 --use-cpan-file-tail
83 Use CPAN's File::Tail module to read the log file instead of the
84 tail(1) command.
85 You may specify only one of the following options:
87 --tail-file=filename or -t filename
89 Examine lines of text as they are added to filename.
90 --read-pipe=command or -p command
92 Examine input piped in from the command.
93 --examine=filename or -f filename
95 Use filename as the file to examine. Swatchdog will do a single
96 pass through the named file.
97 The following options are purely for debugging purposes, but are
99 documented here for completeness:
100 --debug[=level]
102 Spew out various levels of debugging for swatchdog developers.
103 --dump-script[=filename]
105 Instead of running the watcher script after it is generated, it is
106 written to filename or to STDOUT.
107 If swatchdog is called with no options, it is the same as typing the
109 command line
110 swatchdog --config-file=~/.swatchdogrc --tail-file=/var/log/syslog
112 or if /var/log/messages exists
114 swatchdog --config-file=~/.swatchdogrc --tail-file=/var/log/messages
116
118 The configuration file is used by the swatchdog(8) program to determine
119 what types of expression patterns to look for and what type of
120 action(s) should be taken when a pattern is matched.
121 Each line should contain a keyword and a, sometimes optional, value for
123 that keyword. The keyword and value are separated by a space or an
124 equal (=) sign.
125 watchfor regex
127 ignore regex
129 echo [modes]
131 Echo the matched line. The text mode may be normal, bold,
132 underscore, blink, inverse, black, red, green, yellow, blue,
133 magenta, cyan, white, black_h, red_h, green_h, yellow_h, blue_h,
134 magenta_h, cyan_h, and/or white_h. The _h colors specify a
135 highlighting color. The other colors are assigned to the letters.
136 Some modes may not work on some terminals. Normal is the default.
137 bell [N]
139 Echo the matched line, and send a bell N times (default = 1).
140 exec command
142 Execute command. The command may contain variables which are
143 substituted with fields from the matched line. If the
144 --awk-field-syntax command-line option has been specified, then
145 each $N will be replaced by the Nth field in the line. If the
146 option has not been specified, then each $N will refer to a
147 backreference in the regular expression used to match the line.
148 A $0 or $* will always be replaced by the entire line, unless they
150 have been escaped, regardless of the --awk-field-syntax option.
151 An escaped $N, $0 or $* may have unwanted effects since the value
153 will be determined by the shell used to execute the command.
154 mail [addresses=address:address:...][,subject=your_text_here]
156 Send mail to address(es) containing the matched lines as they
157 appear (default address is the user who is running the program).
158 pipe command[,keep_open]
160 Pipe matched lines into command. Use the keep_open option to force
161 the pipe to stay open until a different pipe action is run or until
162 swatchdog exits.
163 write [user:user:...]
165 Use write(1) to send matched lines to user(s).
166 throttle hours:minutes:seconds,[key=message|regex|<regexE]>
168 This action has been depreciated. Use threshold instead For
169 example,
170 throttle 15:00,key="foo"
172 would look like this
174 threshold track_by="foo",type=limit,count=1,seconds=900
176 threshold track_by=key, type=<limit|threshold|both, count=number,
178 seconds=number>
179 Thresholding can be done for the complete watchfor block and/or for
180 individual actions. Add "threshold=on" as an option along with the
181 other threshold options when thresholding an individual action.
182 track_by
184 The value of this should be something that is unique to the
185 watchfor regular expression. Tip: enclose unique parts of the
186 regular expression in parentheses, then use the sub matches as
187 part of the value (e.g. track_by="$2:$4").
188 type
190 There are three types of thresholding. They are as follows:
191 limit
193 Perform action(s) for the first "count" matches during the
194 time interval specified by "seconds", then ignore events
195 for the rest of the time interval (kind of like throttle)
196 threshold
198 Perform action(s) on each match for up to count matches
199 during the time interval specified by seconds
200 both
202 Perform actions(s) once per time interval after "count"
203 matches occur, then ignore additional matches during the
204 time interval specified by "seconds"
205 continue
207 Use this action to cause swatchdog to continue to try to match
208 other pattern/action groups after it is done with the current
209 pattern/action block.
210 quit
212 Use this action to cause swatchdog to clean up and quit
213 immediately.
214
216 The following may be used as an option for any of the above actions
217 except for throttle and threshold.
218 when=day_of_week:hour_of_day
220 Use this option to specify windows of time and days when the action
221 can be performed. For example:
222 mail=sysad-pager@somehost.somedomain,when=1-6:8-17
224
226 perlcode [depth] arbitrary_Perl_code
227 This permits you to easily insert random Perl code into your
228 swatchdogrc file. The optional depth value tells swatchdog how
229 deep into the code to put the perl code. (0=outside the main loop,
230 1=inside the main loop (default), 2=just inside the conditional
231 used by the current watchfor statement, and 3=inside the throttle
232 block).
233 Its intended use is to permit variable substitution. For example:
235 perlcode $syslog="^\w{3}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}.*";
237 watchfor /$syslog hostname pppd/>
239 but any valid Perl is permitted. Remember the semicolon, and make
241 judicious use of the --dump-script option if you run into trouble.
242
244 perlcode my $fsf_regex = '\d{2}:\d{2}:\d{2}\s+(.* file system
245 full)';
246 watchfor /$fsf_regex/
248 threshold track_by=$1,type=limit,count=1,seconds=60
249 echo
250 bell
251 In this example, a line which contains the string "file system full"
253 will be echoed and the screen bell will sound. Also, threshold will
254 use what is matched within the parentheses as its key rather than
255 trying to use the log message with its time stamp cut out. Multiple
256 instances of the message will not be echoed if they appear within a
257 minute of the first one. Instead the following message will be acted
258 upon after the time interval has expired.
259
261 signal(3), perl(1), perlre(1)
262
264 Upon receiving an ALRM or HUP signal swatchdog will re-read the
265 configuration file and restart, except when used with the --daemon
266 command line option where it will simply exit. Swatchdog will
267 terminate gracefully when it receives a QUIT, TERM, or INT signal.
268
270 E. Todd Atkins
271 Todd.Atkins@StanfordAlumni.ORG
272
274 Swatchdog is a SourceForge project whose project page is at
275 http://sourceforge.net/projects/swatchdog and homepage is at
276 http://swatchdog.sourceforge.net
277perl v5.38.0 2023-08-04 SWATCHDOG(1)