Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SWATCHDOG(1)	      User Contributed Perl Documentation	  SWATCHDOG(1)

NAME
       swatchdog - simple watcher

SYNOPSIS
       swatchdog [ --awk-field-syntax ]	[ --config-file|-c file	] [ --daemon ]
       [ --extra-include-dir|-I	path ] [ --extra-module|-M module_name ] [
       --help|-h ] [ --input-record-separator regex ] [	--old-style-config|-O
       ] [ --pid-file file ] [ --restart-time|-r time ]	[ --script-dir path ]
       [ --tail-args arguments_for_tail_program	] [ --tail-program-name
       filename	] [ --version|-V ] [ --use-cpan-file-tail ] [ [	--examine|-f
       file_to_examine ] | [ --read-pipe|-p program_to_pipe_from ] | [
       --tail-file|-t file_to_tail ] ] [ --debug [ level ] ] [ --dump-script
       filename	]

DESCRIPTION
       Swatchdog is designed to	monitor	system activity.  In order for
       Swatchdog 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.

COMMAND	LINE OPTIONS
       --awk-field-syntax
	   Use this option only	if you want to overide regular expression
	   backreferencing in favor of awk(1) style field referencing.
	   Included for	backward compatability.

       --config-file|-c	filename
	   Tells swatchdog where to find its configuration file. The default
	   is ${HOME}/.swatchdogrc.

       --daemon
	   This	tells swatchdog	to run in the background and disassociate
	   itself from any terminal.

       --extra-include-dir|-I path
	   This	tells swatchdog	where to look for custom action	modules.

       --extra-module|-M module_name
	   This	tells swatchdog	what custom action modules to load in.

       --help|-h
	   Prints usage	information and	exits.

       --input-record-separator=regular_expression
	   Tells swatchdog to use regular_expression to	delineate the boundary
	   of each input record. The default is	a carriage return.

       --old-style-config|-O
	   This	tells swatchdog	that your configuration	file is	written	using
	   the syntax that was abandoned back in the 1990's.

       --pid-file file
	   Writes the process ID to file. Useful when running in daemon	mode.

       --restart-time=[+]hh:mm[am|pm] or -r [+]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.

       --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 NOT use directories
	   that	are writable by	others such as /tmp.

       --tail-args arguments_for_tail_program
	   Pass	specific options to the	tail(1)	program.

       --tail-program-name filename
	   Runs	an alternate tail(1) like program instead of the system
	   default.

       --version or -V
	   Prints version information and exits.

       --use-cpan-file-tail
	   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:

       --tail-file=filename or -t filename
	   Examine lines of text as they are added to filename.

       --read-pipe=command or -p command
	   Examine input piped in from the command.

       --examine=filename or -f	filename
	   Use filename	as the file to examine.	 Swatchdog will	do a single
	   pass	through	the named file.

       The following options are purely	for debugging purposes,	but are
       documented here for completeness:

       --debug[=level]
	   Spew	out various levels of debugging	for swatchdog developers.

       --dump-script[=filename]
	   Instead of running the watcher script after it is generated,	it is
	   written to filename or to STDOUT.

       If swatchdog is called with no options, it is the same as typing	the
       command line

	       swatchdog --config-file=~/.swatchdogrc --tail-file=/var/log/syslog

       or if /var/log/messages exists

	       swatchdog --config-file=~/.swatchdogrc --tail-file=/var/log/messages

THE CONFIGURATION FILE
       The configuration file is used by the swatchdog(8) 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

       echo [modes]
	   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. Normal is	the default.

       bell [N]
	   Echo	the matched line, and send a bell N times (default = 1).

       exec command
	   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.

       mail [addresses=address:address:...][,subject=your_text_here]
	   Send	mail to	address(es) containing the matched lines as they
	   appear (default address is the user who is running the program).

       pipe command[,keep_open]
	   Pipe	matched	lines into command. Use	the keep_open option to	force
	   the pipe to stay open until a different pipe	action is run or until
	   swatchdog exits.

       write [user:user:...]
	   Use write(1)	to send	matched	lines to user(s).

       throttle	hours:minutes:seconds,[key=message|regex|<regexE]>
	   This	action has been	depreciated. Use threshold instead For
	   example,

	       throttle	15:00,key="foo"

	   would look like this

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

       threshold track_by=key, type=<limit|threshold|both, count=number,
       seconds=number>
	   Thresholding	can be done for	the complete watchfor block and/or for
	   individual actions. Add "threshold=on" as an	option along with the
	   other threshold options when	thresholding an	individual action.

	   track_by
	       The value of this should	be something that is unique to the
	       watchfor	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").

	   type
	       There are three types of	thresholding. They are as follows:

	       limit
		   Perform action(s) for the first "count" matches during the
		   time	interval specified by "seconds", then ignore events
		   for the rest	of the time interval (kind of like throttle)

	       threshold
		   Perform action(s) on	each match for up to count matches
		   during the time interval specified by seconds

	       both
		   Perform actions(s) once per time interval after "count"
		   matches occur, then ignore additional matches during	the
		   time	interval specified by "seconds"

       continue
	   Use this action to cause swatchdog to continue to try to match
	   other pattern/action	groups after it	is done	with the current
	   pattern/action block.

       quit
	   Use this action to cause swatchdog to clean up and quit
	   immediately.

SPECIAL	OPTION
       The following may be used as an option for any of the above actions
       except for throttle and threshold.

       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:

	       mail=sysad-pager@somehost.somedomain,when=1-6:8-17

FOR PERL HACKS ONLY
       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).

	   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	--dump-script option if	you run	into trouble.

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

SEE ALSO
       signal(3), perl(1), perlre(1)

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

AUTHOR
	   E. Todd Atkins
	   Todd.Atkins@StanfordAlumni.ORG

AVAILABILITY
       Swatchdog is a SourceForge project whose	project	page is	at
       http://sourceforge.net/projects/swatchdog and homepage is at
       http://swatchdog.sourceforge.net

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 1350:
	   You forgot a	'=back'	before '=head1'

perl v5.32.1			  2015-09-29			  SWATCHDOG(1)

NAME | SYNOPSIS | DESCRIPTION | COMMAND LINE OPTIONS | THE CONFIGURATION FILE | SPECIAL OPTION | FOR PERL HACKS ONLY | CONFIGURATION EXAMPLE | SEE ALSO | NOTES | AUTHOR | AVAILABILITY | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=swatchdog&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help