Swatch: Simple Log File Watcher Guide

Swatch isn’t a cleverly designed watch from the 1980s but you’ll think it’s just as handy (and cleverly designed) as one. Like Logwatchswatch is a perl script that watches your logs but swatch watches them for regular expressions that you configure. Swatch will notify you via mail or the console screen (stdout) when it matches the configured log file entries with your watchfor directives.

Swatch picks up and delivers messages as intrusions occur so that you can halt any potential breakins or hacks before the intruder does any damage. It is one of the most important defensive weapons in your system administrator arsenal.

The Basics

The Swatch Project page is the first place you need to visit so that you can grab the source code and get started. If you’re lucky, your distribution will have a pre-built package for you to install. Packaged version or not, you have some work to do before swatch will work. The man page is helpful for basic information to run and configure swatch. Pay particular attention to the COMMAND LINE OPTIONS and THE CONFIGURATION FILEsections. You can find a bit more help under /usr/share/doc/swatch.

The information in this article comes from some trial and error in dealing with and configuring this latest version (3.2.3) of swatch using the information provided by the swatch man page and the included doc file.

The Swatch Startup Script

You’ll want to setup a startup script so that swatch launches every time you have to reboot your system. This script also provides a manual startup and shutdown mechanism for swatch. You’ll need to recycle swatch each time you make a change to its configuration file. Create the example startup script (below) as /etc/init.d/swatch.

# Simple Log Watcher Program

case "$1" in
		/usr/bin/swatch --daemon --config-file=/etc/swatch.conf --tail-file=/var/log/auth.log --pid-file=/var/run/swatch.pid
		PID=`cat /var/run/swatch.pid`
		kill $PID
		echo "Usage: $0 { start | stop }
exit 0

Then to make sure that swatch starts up in your standard runlevels, you’ll need to perform the following tasks.

$ sudo chmod 755 /etc/init.d/swatch
$ sudo ln -s /etc/init.d/swatch /etc/rc2.d/S99swatch
$ sudo ln -s /etc/init.d/swatch /etc/rc3.d/S99swatch
$ sudo ln -s /etc/init.d/swatch /etc/rc5.d/S99swatch

The Swatch Command

The swatch command parameters shown in the startup script above require some explanation. Remember that you can test any new parameter or configuration options by using swatch at the command line. You don’t have to change it in the startup script and restart it for testing. Let’s dissect this very basic but very functional swatch command.

/usr/bin/swatch --daemon --config-file=/etc/swatch.conf --tail-file=/var/log/auth.log --pid-file=/var/run/swatch.pid

/usr/sbin/swatch is the full explicit path to the swatch script (command). When scripting, you should always use explicit paths to alleviate any annoying “command not found” messages due to $PATH problems.

The –daemon option tells swatch to run as a daemon.

The –config-file=/etc/swatch.conf option refers to the swatch configuration file that contains your alert directives and instructions. Swatch requires that you create and use a configuration file.

The –tail-file=/var/log/auth.log entry tells swatch which log file you want to watch. You may watch more than one log file by adding it to the list. For example, –tail-file=/var/log/auth.log /var/log/messages.

You can specify a PID (Process ID) file with the –pid-file option. Using this option makes it easier to script a “kill” or shutdown for swatch as you can see in the Startup Script section.

Should you decide to alter an option, you can test it at the command line with or without the –daemon option. Remember to restart swatch each time you change a parameter to force swatch to reread the configuration file.


The default configuration file is the .swatchrc located in the swatch user’s home directory. Swatch can use any filename as a configuration if it’s specified in the command line argument. This means that you can create a system-level swatch that watches logs in /var/log and individual swatch log watchers for other programs that don’t necessarily drop their log files into /var/log. It also means that you can individualize swatch log watchers on a per user basis and any user can run swatch.

Let’s look at a system-level swatch configuration and then you can extrapolate it for individual swatch log watchers. The /etc directory is the logical location for a system-level configuration file, so let’s use /etc/swatch.conf for the system-level configuration file.

The /etc/swatch.conf file contains all of your watchfor and ignore directives. It also holds your notification email addresses. See a simple swatch.conf below.

watchfor /invalid|repeated|incomplete/
		 write khess
		 mail addresses=khess@localhost, subject=Authentication Problems

The watchfor entry is a list of keywords that you want to alert on so that when the system writes an entry containing one or more of your keywords, swatch will take any actions that follow the watchfor line. The echo line tells swatch to echo the alert to the console screen. The write line tells swatch to write the message to the user’s terminal. You can see an example of this write command in action in Figure 1. The last line in this configuration file tells swatch to mail those offending captured entries to the person(s) listed.

Figure 1: Intruder detection notification sent via the write configuration option.

Refer to the listing below to see what the output to mail looks like.

$ mail
>U   1 root     Tue Jun  8 06:43 17/579  Authentication Problems
 U   2 root     Tue Jun  8 06:43 16/544  Authentication Problems
 U   3 root     Tue Jun  8 06:43 16/546  Authentication Problems

The contents of the mail message you receive is the excerpted entry from the auth.log file you defined for the swatch command.

Jun 8 06:43:54 kubuntu sshd [1618]: Failed none for invalid user freddy from port 37800 ssh2

Interactive Session Notification

An attempt on your system looks like the following listing as it occurs. These messages appear on the console screen of the target host running swatch. These warnings give you a real time notification that a possible breakin attempt is in progress and allows you to take action.

If you use the write option in the configuration file, you’ll also see the messages shown in Figure 1 (above) as the attempt occurs.

Jun 8 06:43:41 kubuntu sshd[1618]: Invalid user freddy from
Jun 8 06:43:41 kubuntu sshd[1618]: Failed none for invalid user freddy from port 378000 ssh2
Jun 8 06:43:46 kubuntu sshd[1618]: Failed none for invalid user freddy from port 378000 ssh2
Jun 8 06:43:50 kubuntu sshd[1618]: Failed none for invalid user freddy from port 378000 ssh2
Jun 8 06:43:54 kubuntu sshd[1618]: Failed none for invalid user freddy from port 378000 ssh2

Swatch is an excellent “catch them in the act” log monitoring tool. Using swatch provides you with a real time trap for those would be hackers and system crackers. With swatch, these blackhatted types will never have a chance to break in and cover their tracks. You can stop them cold by knowing what time it is.

Next week, we temporarily divert your attention from logs to a look at how to expand those ever-filling virtual machine filesystems.