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