Configuration

In these next two sections, I'll use the Postfix mail server as an example. Because of the vast possibilities available in customizing logwatch, I have only scanned through the configuration options briefly; however, the HOWTO file offers plenty of additional advice should you need it.

If you look at the config file, /usr/share/logwatch/default.conf/services/postfix.conf, you will see that it takes 327 lines of comments and code just to parse the logs for this one application.

Filters

Now you're ready to create your own logwatch filters. The very structure of logwatch makes it what you might call pluggable or modular. By that, I mean that you can keep adding application filters to your heart's content. By writing your own customized versions of filters, the intelligent logwatch reports according to your preferences, with the most suitable level of detail for your needs.

I will now take a look at the Postfix filter example. Even if you don't delve into the /usr/share/logwatch/scripts/services/postfix filter file too deeply, you can see the following pattern-matching rules in place to capture SSL certificate logging errors and events (Listing 1).

push @ignore_list, qr/^Peer verification:/;
push @ignore_list, qr/^Server certificate could not be verified/;
push @ignore_list, qr/^cannot load .SA certificate and key data/;
push @ignore_list, qr/^tlsmgr_cache_run_event/;
push @ignore_list, qr/^SSL_accept/;
push @ignore_list, qr/^SSL_connect:/;
push @ignore_list, qr/^connection (?:closed|established)/;

These lines are much easier to understand than other parts of the script, and I'm pointing this out so you can add more lines to these rules or modify them slightly if you ever have the need.

To get started creating your own filters, I encourage you to look at config and script files held within /usr/share/logwatch. You can then remove anything from the example filters already there that you don't need. On that note, if you make any small mistakes, don't worry, because logwatch cleverly ignores and removes any duplicate values, so you're safe with a typo or two.

To begin, you create a logfile group, which is essentially a list of logfiles, and then you need to create a service filter. You can then save these in /etc/logwatch/conf/services/ with the filename format chris_new_service.conf. Creating a logfile group requires only one config line, as in the following:

LogFile = /var/log/messages
LogFile = /var/log/syslog
LogFile = /var/log/authd.log

The caveat here is that LogFile = messages refers to the logfile group named messages and not the filename, so if you don't keep system syslog messages inside the file /var/log/messages or if you've changed your logging path in logwatch, you should declare a full path.

To allow details to pass between your config files, you can use:

*SharedScriptName = Arguments

These pre-written shared scripts reside in /usr/share/logwatch/scripts/shared. If you look in that directory, you will see a number of existing scripts (Listing 2), and you can provide variables accessible to your filter:

applybinddate* applystddate*
eventlogonlyservice* hosthash*
onlycontains* remove* applyeurodate*
applytaidate* eventlogremoveservice*
hostlist* onlyhost* removeheaders*
applyhttpdate* applyusdate* expandrepeats*

$EnvironmentVariable = Sula

In your config files; you can incorporate Bash scripts as well as Perl scripts; that is, you can trigger (from within the scripts/ directory) any script capable of pattern-matching or text manipulation.

The HOWTO docs provide an insightful filter example (Listing 3) with a perfect amount of detail. You should try tweaking this example as an exercise. If in doubt, reference the filters already in use by other applications for inspiration.

01 #!/bin/bash
02 # This is as nice script that will show you the lines you will
03 # be processing and reporting on.  It will first display the
04 # standard environment variables and then it takes STDIN and
05 # dump it right back out to STDOUT.
06
07 # These are the standard environment variables.  You can define
08 # more in your service config file (see above).
09 echo "Date Range: $LOGWATCH_DATE_RANGE"
10 echo "Detail Level: $LOGWATCH_DETAIL_LEVEL"
11 echo "Temp Dir: $LOGWATCH_TEMP_DIR"
12 echo "Debug Level: $LOGWATCH_DEBUG"
13
14 # Now take STDIN and dump it to STDOUT
15 cat

Once you have written your filter, save the file in the directory /etc/logwatch/scripts/services/ and call it something like name_filter. Naming is important because you then create your config file as name_filter.conf, which would live in the directory /usr/share/logwatch/dist.conf/logfiles/. Its contents might then be LogFile = name.log.1. At first, I was a little lost with file paths, especially because I first used this on a non-Debian system, so if you get stuck, just check the "HOWTO" again for the specifics for your operating system. The file that helped me the most when working on Debian was /usr/share/doc/logwatch/README.Debian.

A word of advice about how logwatch was ported to Debian from Red Hat suggests the easiest way to create your own filters is as follows: "… copy the filterscript from /usr/share/logwatch/scripts to /etc/logwatch/scripts, preserving the hierarchy. Then modify it. The disadvantage is that you will not be able to track upstream changes" [3].

Incidentally, any custom filters you create will apparently be welcomed at the logwatch SourceForge site [4] if there is likely to be any interest in other people in using them.

Conclusions

Despite the complexity of structure and Perl scripts, there's little debate that logwatch is exceptionally well constructed. Even many enterprise applications don't provide such a comprehensive out-of-the-box experience coupled with such varied, extensible, customization options. With some tinkering, even the porting of packages between different operating systems shouldn't be too difficult.

In this article, I hoped to provide you with enough information to get started using logwatch. That said, you might want to keep an eye out for a time where writing your own custom filter becomes a useful addition to your logging arsenal.