1SWATCH(1)             User Contributed Perl Documentation            SWATCH(1)
2
3
4

NAME

6       swatch - simple watcher
7

SYNOPSIS

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

DESCRIPTION

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

COMMAND LINE OPTIONS

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
30       --config-file|-c filename
31           Tells swatch where to find its configuration file. The default is
32           ${HOME}/.swatchrc.
33
34       --daemon
35           This tells swatch to run in the background and disassociate itself
36           from any terminal.
37
38       --extra-include-dir|-I path
39           This tells swatch where to look for custom action modules.
40
41       --extra-module|-M module_name
42           This tells swatch what custom action modules to load in.
43
44       --help|-h
45           Prints usage information and exits.
46
47       --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
51       --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
55       --pid-file file
56           Writes the process ID to file. Useful when running in daemon mode.
57
58       --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
65       --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
71       --tail-args arguments_for_tail_program
72           Pass specific options to the tail(1) program.
73
74       --tail-program-name filename
75           Runs an alternate tail(1) like program instead of the system
76           default.
77
78       --version or -V
79           Prints version information and exits.
80
81       --use-cpan-file-tail
82           Use CPAN's File::Tail module to read the log file instead of the
83           tail(1) command.
84
85       You may specify only one of the following options:
86
87       --tail-file=filename or -t filename
88           Examine lines of text as they are added to filename.
89
90       --read-pipe=command or -p command
91           Examine input piped in from the command.
92
93       --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
97       The following options are purely for debugging purposes, but are
98       documented here for completeness:
99
100       --debug[=level]
101           Spew out various levels of debugging for swatch developers.
102
103       --dump-script[=filename]
104           Instead of running the watcher script after it is generated, it is
105           written to filename or to STDOUT.
106
107       If swatch is called with no options, it is the same as typing the
108       command line
109
110               swatch --config-file=~/.swatchrc --tail-file=/var/log/syslog
111
112       or if /var/log/messages exists
113
114               swatch --config-file=~/.swatchrc --tail-file=/var/log/messages
115

THE CONFIGURATION FILE

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
121       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
125       watchfor regex
126
127       ignore regex
128
129       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
137       bell [N]
138           Echo the matched line, and send a bell N times (default = 1).
139
140       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
148           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
151           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
154       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
158       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
163       write [user:user:...]
164           Use write(1) to send matched lines to user(s).
165
166       throttle hours:minutes:seconds,[key=message|regex|<regexE]>
167           This action has been depreciated. Use threshold instead For
168           example,
169
170               throttle 15:00,key="foo"
171
172           would look like this
173
174               threshold track_by="foo",type=limit,count=1,seconds=900
175
176       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
182           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
188           type
189               There are three types of thresholding. They are as follows:
190
191               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
196               threshold
197                   Perform action(s) on each match for up to count matches
198                   during the time interval specified by seconds
199
200               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
205       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
210       quit
211           Use this action to cause swatch to clean up and quit immediately.
212

SPECIAL OPTION

214       The following may be used as an option for any of the above actions
215       except for throttle and threshold.
216
217       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
221               mail=sysad-pager@somehost.somedomain,when=1-6:8-17
222

FOR PERL HACKS ONLY

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
231           Its intended use is to permit variable substitution. For example:
232
233               perlcode $syslog="^\w{3}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}.*";
234
235               watchfor /$syslog hostname pppd/>
236
237           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

CONFIGURATION EXAMPLE

241           perlcode my $fsf_regex = '\d{2}:\d{2}:\d{2}\s+(.* file system
242           full)';
243
244           watchfor /$fsf_regex/
245               threshold track_by=$1,type=limit,count=1,seconds=60
246               echo
247               bell
248
249       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

SEE ALSO

258       signal(3), perl(1), perlre(1)
259

NOTES

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

AUTHOR

267           E. Todd Atkins
268           Todd.Atkins@StanfordAlumni.ORG
269

AVAILABILITY

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
274
275
276
277perl v5.36.0                      2023-01-21                         SWATCH(1)
Impressum