SWATCHDOG(1p)

📦
version 3.2.4 · 3 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing

🌸 SWATCHDOG(1p) 🌸

okay bestie, welcome to the swatchdog page — that's section 1p, straight out of the User Contributed Perl Documentation. she's a simple watcher and she's iconic, let's get into it 💅

✨ 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 💖

So, Swatchdog is built to monitor system activity. lowkey her whole thing 🫶

But here's the tea: for Swatchdog to actually be useful, she needs a configuration file. That file is where you put the pattern(s) to look for, and the action(s) to do whenever one of those patterns gets matched. No config, no vibes. periodt.

👑 COMMAND LINE OPTIONS 👑

  • --awk-field-syntax — only use this one if you wanna override regular expression backreferencing and go with awk(1) style field referencing instead. it's here for backward compatibility, bestie, she's a legacy queen 💀
  • --config-file|-c filename — tells swatchdog where her configuration file lives. the default is ${HOME}/.swatchdogrc.
  • --daemon — tells swatchdog to run in the background and disassociate herself from any terminal. main character going off-grid ✨
  • --extra-include-dir|-I path — tells swatchdog where to look for custom action modules.
  • --extra-module|-M module_name — tells swatchdog which custom action modules to load in.
  • --help|-h — prints usage info and dips out.
  • --input-record-separator=regular_expression — tells swatchdog to use regular_expression to mark the boundary of each input record. the default is a carriage return.
  • --old-style-config|-O — tells swatchdog your config file is written in the syntax that got abandoned back in the 1990's. vintage fr fr 🕰️
  • --pid-file file — writes the process ID to file. super useful when you're 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 you leave out the am/pm indicator, a 24-hour clock is assumed. and if the time is preceded by the + character, then the restart time gets set to the current time plus the specified time, and the am/pm indicator gets ignored entirely.
  • --script-dir=/path/to/directory — this switch makes the temporary watcher script get written to a file in the specified directory instead of the user's home directory.
⚠️ it is highly advised that you do NOT use directories that are writable by others such as /tmp. seriously bestie, don't do it 🙈
  • --tail-args arguments_for_tail_program — pass specific options through 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 info 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 🎀

pick your fighter, bestie, you only get one:

  • --tail-file=filename or -t filename — examine lines of text as they get 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 debug girlies (documented for completeness)

The following options are purely for debugging purposes, but they're 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's generated, it gets written to filename or to STDOUT.

🦋 the no-options vibe 🦋

If swatchdog is called with no options at all, it's 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 what the swatchdog(8) program uses to figure out what types of expression patterns to look for, and what type of action(s) to take when a pattern is matched.

Every line should have 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, clear, reset, bold underline, underscore, blink, reverse, concealed, black, red green, yellow, blue, magenta, on_black, on_red, on_green on_yellow, on_blue, on_magenta, on_cyan, on_white. The <on_> colors specify a highlighting color. Some modes may not work on some terminals. Normal is the default. For modes changes and additions, check the perl module Term::ANSIColor man page.
  • bell [N] — echo the matched line, and send a bell N times (default = 1). 🔔
  • exec command — execute command. The command may contain variables which get substituted with fields from the matched line. If the --awk-field-syntax command-line option has been specified, then each $N will be replaced by the Nth field in the line. If the option has not been specified, then each $N will refer to a backreference in the regular expression used to match the line.

A $0 or $* will always be replaced by the entire line, unless they've been escaped, regardless of the --awk-field-syntax option.

An escaped $N, $0 or $* may have unwanted effects since the value will be determined by the shell used to execute the command.

  • 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's 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 keep trying to match other pattern/action groups after she's done with the current pattern/action block. she's not done yet 💅
  • 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 🍓

perlcode my $fsf_regex = '\d{2}:\d{2}:\d{2}\s+(.* file system full)';

watchfor /$fsf_regex/
    threshold track_by=$1,type=limit,count=1,seconds=60
    echo
    bell

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's 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. no cap 🔥

💜 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 she'll simply exit. Swatchdog will terminate gracefully when she receives a QUIT, TERM, or INT signal. she's dramatic but she's polite ✨

🎀 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

and that's the whole page bestie, you ate 💅 this was served up by perl v5.36.0, dated 2023-01-20, and it's the SWATCHDOG(1p) page — go forth and watch things, queen 👑💖

📦 where this page comes from