multilog-watch

(Filters a syslog file and mails the results)

SYNOPSIS

multilog-watch [-hv] config

DESCRIPTION

multilog-watch parses the logs in a multilog(1) directory, picking up where the last invocation left off, and filters out all of the boring lines as configured in config. It then mails any remaining lines, if any, to the address specified in config. The mail is sent using qmail-remote to bypass any problems with the mail system on the host, which means that this program will only work on a system running qmail.

If config isn't an absolute path, it's taken to be relative to /etc/leland.

The TAI64N timestamps in the multilog log files are converted to an ISO-style human-readable form for the mail message.

OPTIONS

-h, --help

Print out this documentation (which is done simply by feeding the script to perldoc -t).

-v, --version

Print the version of filter-syslog and exit.

CONFIGURATION FILE

There are two types of valid lines in the configuration file; variable settings, and filter patterns. A variable setting looks like:

    variable = value

where value can contain whitespace (but can't begin with whitespace). A filter pattern looks like:

    /regex/

where regex is a regular expression matching lines that are "boring" and shouldn't be reported (sans the initial timestamp).

The following variables are recognized:

alert

The address to which to mail the filtering results. No mail will be sent if all of the input lines are filtered out by the regexes provided. This variable must be set.

dir

The multilog directory to filter. Note that the parent directory has to be writable by the user running multilog-watch, so that it can save its timestamp for the last time the log was checked. This variable must be set.

sender

The address from which to mail the filtering results (used for the envelope sender and the To: header). This variable must be set.

server

The server through which to send mail with qmail-remote. This server should be fairly reliable and rarely down, since if it is the mail may be lost. This variable must be set.

subject

The value to use for the Subject: header of the filtering results. This variable must be set.

If there are any input lines that don't match one of the filter rules, they will be mailed to the value of alert with a subject given by subject.

EXAMPLES

Use the configuration file /etc/leland/qmail.filter and filter the log directory given in it:

    multilog-watch /etc/leland/qmail.filter

Here's a sample configuration file that filters out normal qmail messages from the logs in /var/log/qmail and sends the result to root@example.com with a Subject: header of "example syslog filter results", using smtp.example.com as the sending server. The return address will also be root@example.com

    dir = /var/log/qmail
    alert = root@example.com
    sender = root@example.com
    server = smtp.example.com
    subject = example syslog filter results

    /^new msg \d+$/
    /^info msg \d+:/
    /^starting delivery \d+:/
    /^status:/
    /^delivery \d+: success:/
    /^end msg \d+$/

This particular configuration would mail to root@example.com every message related to an unsuccessful mail delivery.

FILES

/etc/leland

If the configuration file given on the command line isn't an absolute path, it is looked for in this directory. This default can be changed at the top of this program.

multilog-watch creates a file named dir.last where dir is the name of the directory that it's filtering, containing the timestamp of the last successful filter run. It reads this file if its present and ignores any log messages before that time. This is both an optimization to keep from having to reparse logs and a way to keep from sending duplicate reports about abnormal messages.

BUGS

multilog-watch makes no attempt to handle leap seconds or to handle TAI to UTC conversion correctly. It was written with hard-coded adjustments for systems where the system clock is in UTC and no leap seconds file is present. In that situation, software generating TAI64N timestamps will generate timestamps with an epoch 10 seconds different than UTC, which multilog-watch adjusts for.

This is obviously not the correct approach, which would be to use logic analogous to what libtai does. It was just the expedient thing to do for my immediate problem.

SEE ALSO

See <http://cr.yp.to/daemontools.html> for information on multilog and the rest of the daemontools package.

The current version of this program is available from its web page at <http://www.eyrie.org/~eagle/software/multilog-watch/>.

AUTHOR

Russ Allbery <rra@stanford.edu>

COPYRIGHT AND LICENSE

Copyright 2001, 2002, 2004 Board of Trustees, Leland Stanford Jr. University.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

Last spun 2022-12-12 from POD modified 2004-12-09