Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  SWATCH (1)

.ds Aq ’


swatch - simple watcher



<B>swatchB> [ <B>--awk-field-syntaxB> ] [ <B>--config-file|-cB> file ] [ <B>--daemonB> ] [ <B>--extra-include-dir|-IB> path ] [ <B>--extra-module|-MB> module_name ] [ <B>--help|-hB> ] [ <B>--input-record-separatorB> regex ] [ <B>--old-style-config|-OB> ] [ <B>--pid-fileB> file ] [ <B>--restart-time|-rB> time ] [ <B>--script-dirB> path ] [ <B>--tail-argsB> arguments_for_tail_program ] [ <B>--tail-program-nameB> filename ] [ <B>--version|-VB> ] [ <B>--use-cpan-file-tailB> ] [ [ <B>--examine|-fB> file_to_examine ] | [ <B>--read-pipe|-pB> program_to_pipe_from ] | [ <B>--tail-file|-tB> file_to_tail ] ] [ <B>--debugB> [ level ] ] [ <B>--dump-scriptB> filename ]


<B>SwatchB> is designed to monitor system activity. In order for <B>SwatchB> to be useful, it requires a configuration file which contains pattern(s) to look for and action(s) to perform when each pattern is found.


<B>--awk-field-syntaxB> Use this option only if you want to overide regular expression backreferencing in favor of <B>B>awk<B>(1)B> style field referencing. Included for backward compatability.
<B>--config-file|-cB> filename Tells <B>swatchB> where to find its configuration file. The default is ${HOME}/.swatchrc.
<B>--daemonB> This tells <B>swatchB> to run in the background and disassociate itself from any terminal.
<B>--extra-include-dir|-IB> path This tells <B>swatchB> where to look for custom action modules.
<B>--extra-module|-MB> module_name This tells <B>swatchB> what custom action modules to load in.
<B>--help|-hB> Prints usage information and exits.
<B>--input-record-separatorB>=regular_expression Tells <B>swatchB> to use regular_expression to delineate the boundary of each input record. The default is a carriage return.
<B>--old-style-config|-OB> This tells <B>swatchB> that your configuration file is written using the syntax that was abandoned back in the 1990’s.
<B>--pid-fileB> file Writes the process ID to file. Useful when running in daemon mode.
<B>--restart-timeB>=[+]hh:mm[am|pm] or <B>-rB> [+]hh:mm[am|pm] Restart at the specified time where hh is hours and mm is minutes. If the am/pm indicator is omitted, then a 24-hour clock is assumed. If the time is preceded by the + character, then the restart time will be set to the current time plus the specified time and the am/pm indicator will be ignored.
<B>--script-dirB>=/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 <B>NOTB> use directories that are writable by others such as /tmp.
<B>--tail-argsB> arguments_for_tail_program Pass specific options to the <B>B>tail<B>(1)B> program.
<B>--tail-program-nameB> filename Runs an alternate <B>B>tail<B>(1)B> like program instead of the system default.
<B>--versionB> or <B>-VB> Prints version information and exits.
<B>--use-cpan-file-tailB> Use CPAN’s File::Tail module to read the log file instead of the tail(1) command.
You may specify only one of the following options:
<B>--tail-fileB>=filename or <B>-tB> filename Examine lines of text as they are added to filename.
<B>--read-pipeB>=command or <B>-pB> command Examine input piped in from the command.
<B>--examineB>=filename or <B>-fB> filename Use filename as the file to examine. <B>SwatchB> will do a single pass through the named file.
The following options are purely for debugging purposes, but are documented here for completeness:
<B>--debugB>[=level] Spew out various levels of debugging for swatch developers.
<B>--dump-scriptB>[=filename] Instead of running the watcher script after it is generated, it is written to filename or to STDOUT.
If swatch is called with no options, it is the same as typing the command line

        swatch --config-file=~/.swatchrc --tail-file=/var/log/syslog

or if /var/log/messages exists

        swatch --config-file=~/.swatchrc --tail-file=/var/log/messages


The configuration file is used by the <B>B>swatch<B>(8)B> 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.

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.

watchfor regex

ignore regex
<B>echo [modes]B> 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. The other colors are assigned to the letters. Some modes may not work on some terminals. <B>NormalB> is the default.
<B>bell [N]B> Echo the matched line, and send a bell N times (default = 1).
<B>exec commandB> Execute command. The command may contain variables which are substituted with fields from the matched line. A $N will be replaced by the Nth field in the line. A $0 or $* will be replaced by the entire line.
<B>mail [addresses=address:address:...][,subject=your_text_here]B> Send mail to address(es) containing the matched lines as they appear (default address is the user who is running the program).
<B>pipe command[,keep_open]B> Pipe matched lines into command. Use the <B>keep_openB> option to force the pipe to stay open until a different pipe action is run or until swatch exits.
<B>write [user:user:...]B> Use <B>B>write<B>(1)B> to send matched lines to user(s).
<B>throttle hours:minutes:seconds,[key=message|regex|<regexEB>]> This action has been depreciated. Use <B>thresholdB> instead For example,

  throttle 15:00,key=foo

would look like this

  threshold track_by=foo,type=limit,count=1,seconds=900

<B>threshold track_by=key, type=<limit|threshold|bothB>, count=number, seconds=number> Thresholding can be done for the complete <B>watchforB> block and/or for individual actions. Add threshold=on as an option along with the other threshold options when thresholding an individual action.
<B>track_byB> The value of this should be something that is unique to the <B>watchforB> 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=$2:$4).
<B>typeB> There are three types of thresholding. They are as follows:
<B>limitB> Perform action(s) for the first "<B>countB> matches during the time interval specified by <B>secondsB>", then ignore events for the rest of the time interval (kind of like throttle)
<B>thresholdB> Perform action(s) on each match for up to <B>countB> matches during the time interval specified by <B>secondsB>
<B>bothB> Perform actions(s) once per time interval after "<B>countB> matches occur, then ignore additional matches during the time interval specified by <B>secondsB>"
<B>continueB> Use this action to cause <B>swatchB> to continue to try to match other pattern/action groups after it is done with the current pattern/action block.
<B>quitB> Use this action to cause <B>swatchB> to clean up and quit immediately.


The following may be used as an option for any of the above actions except for throttle and threshold.
<B>when=B>day_of_week:hour_of_day Use this option to specify windows of time and days when the action can be performed. For example:



<B>perlcodeB> [depth] arbitrary_Perl_code This permits you to easily insert random Perl code into your swatchrc file. The optional depth value tells swatch 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).

Its intended use is to permit variable substitution. For example:

  perlcode $syslog=^\w{3}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}.*;

watchfor /$syslog hostname pppd/>

but any valid Perl is permitted. Remember the semicolon, and make judicious use of the <B>--dump-scriptB> option if you run into trouble.


In this example, a line which contains the string file system full will be echoed and the screen bell will sound. Also, <B>thresholdB> 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.


<B>B>signal<B>(3)B>, <B>B>perl<B>(1)B>, <B>B>perlre<B>(1)B>


Upon receiving an ALRM or HUP signal swatch will re-read the configuration file and restart, except when used with the --daemon command line option where it will simply exit. Swatch will terminate gracefully when it receives a QUIT, TERM, or INT signal.


    E. Todd Atkins


Swatch is a SourceForge project whose project page is at and homepage is at


Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 1350: You forgot a ’=back’ before ’=head1’
Search for    or go to Top of page |  Section 1 |  Main Index

perl v5.20.3 SWATCH (1) 2008-07-01

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.