LOGFMON.CONF(5)

NAME
logfmon.conf - log file monitoring daemon configuration file

DESCRIPTION
This manual page describes the logfmon(8) configuration file. It has the following format:

Empty lines and lines beginning with the ‘#’ character are ignored.

Regexps and strings must be enclosed in double quotes. Special characters in regexps and strings must be escaped. Note that this may mean double-escaping in regexps.

Possible commands are covered in the following sections.

OPTIONS
Options are configured using the set command. It may be followed by the following options, one per command:

mailtime time
    This is used to set the time between mails of unmatched messages.

    The time may be specified as a plain number in seconds or with a suffix of ‘h’ for hours, ‘m’ for minutes or ‘s’ for seconds. The default is 15 minutes and the minimum is 10 seconds.

mailcmd command
    This sets the command to which the mail is piped. For example:

    set mailcmd "/usr/bin/mail -s \"`date` log report\" root"

    No mail will be sent if the command is an empty string ("").

user user | uid
    This instructs logfmon(8) to run as a different user or uid. In common with other strings, a user name must be in double quotes. An alternative user will only be used if logfmon(8) is run as root.

    It is important to note that when logfmon(8) runs as a different user or group, it will still need read access to any log files specified with a file command and the ability to execute any external commands (including the mailcmd setting) specified in the configuration file.

group group | gid
    This instructs logfmon(8) to run as a different group or gid. An alternative group will only be used if logfmon(8) is run as root.

cachefile file
    This informs logfmon(8) of the path of the file used to retain a cache of the offsets and sizes of the log files to prevent duplicate processing of entries when it is restarted. An empty string disables caching. Note that this option may be overridden on the command line. The default setting is /var/db/logfmon.cache.

pidfile file
    This instructs logfmon(8) to write its pid into the file specified. If an empty string is used, the pid is not written. If this entry does not appear in the configuration file, the default of /var/run/logfmon.pid is used. Note that this option may be overridden on the command line.

logregexp regexp
    This sets the regexp that logfmon(8) uses to select the part of each log line which is to be compared against the ruleset. The first submatch (enclosed in parenthesis) is used. The default regexp is set for syslog(3) format:

    ^[A-Z][a-z][a-z] [0-9 ][0-9] [0-9][0-9]:[0-9][0-9]:[0-9][0-9] [^ ]* (.*)$

maxthreads number
    This sets the maximum number of threads logfmon(8) will attempt to start simultaneously. If this number is reached, logfmon(8) will block until some of the threads exit. The default is 100.

MACROS
Macros may be defined using the following syntax:

$name = string

%name = number

Macros are prefixed with $ to indicate a string value and % to indicate a numeric value. Once defined, a macro may be used in any place a string or number is expected. Macros may be embedded in strings by surrounding their name (after the $ or %) with {}s, like so:

"abc ${mymacro} %{anothermacro} def"

FILES
The file command is used to instruct logfmon(8) to monitor a file. The filename must be given as a parameter.

Optionally, the file may be given a tag by specifying tag tag following the filename. This tag is used in match rules, described below, to restrict matches to a particular file. The tag is restricted to alphanumeric characters, hyphens and underscores. If no tag is given for a file, logfmon(8) assigns it a tag.

An example of a file command is:

file "/var/log/daemon" tag daemon

RULES
Rules are described using the match command. This section describes simple rules, contexts are covered in a seperate section below.

Each match command gives logfmon(8) a regexp to test each new log entry against, an action to perform and optionally a tag or set of tags to restrict matches to a single file.

The format of a match command is:

match
    [in tags] regexp [not regexp] action

If the in tags part is not supplied, or is a single asterisk, the rule is applied in all files. A rule may be applied to multiple tags by enclosing them in braces, for example { tag1 tag2 tag3 }. Braces are not necessary for a single tag.

If a not regexp part is supplied, the rule only applies if the log entry both matches the first regexp and doesn't match the second, not, regexp.

For this form of match command, testing of a log entry is stopped as soon as a matching rule is found.

The possible actions are:

ignore
    Any matched log entries in the specified files are ignored. They are not batched into the unmatched email and are tested against no further rules.

    An example ignore rule is:

    match in daemon "ntpd\\[[0-9]*\\]: adjusting local clock by [0-9.-]*s" ignore

exec command
    This executes command when a matching entry is seen. $0 is replaced in the command with the entire log entry and $1 to $9 are replaced with any bracketted match expressions in the regexp.

    An example exec rule is:

    match "sshd\\[[0-9]*\\]: Invalid user .* from ([0-9.]*)" exec "grep $1 /etc/pf.ignore || (echo $1 >> /etc/pf.ignore; pfctl -t ignore -T add $1; pfctl -k $1; echo $0 | mail -s 'ssh attempt' root)"

pipe command
    With this action, the entire log entry is piped to the supplied command

write file
    This action writes the log entry to the specified file, creating it if it does not exist and truncating it if it does.

write-append file
    This appends the entire log entry to a file.

CONTEXTS
A context is a set of log entries that has been collected together. A context is opened by an open action on a match rule, messages may be appended to it with an append action, it may be closed and an action taken with a close rule and an action taken on the collected log entries and the context emptied without being removed by using the clear action.

A context expires and is removed after a time supplied to the open rule. An action may be taken when a context expires, or, with a when command, optionally when it reaches a certain number of entries. If a pipe action is used, then $1 to $9 is replaced by any match expressions from the matched log line before the context is piped to it.

Note that unlike the other rules, logfmon(8) does not stop parsing rules when a message matches a context rule. This means that without a matching ignore rule, messages that match any of the context rules described below will be included in the email of unmatched rules. This also means, however, that messages matching an open can be included in the context with an append command, or indeed used to exec or pipe in later rules.

The forms of match command relating to contexts are described below. All the non-context actions, ignore, pipe, exec, write and write-append, are permitted in rules where action appears below. When pipe is used, the entire context is piped to the supplied command. When write or write-append are used, logfmon(8) attempts to write the context to the specified file, overwriting with the former and appending with the latter.

match
    [in tags] regexp [not regexp] open name [autoappend] expire time action [when num action] This opens a context with name name and sets it to expire after the time specified. time is in the same format as for the set mailtime command. $0 to $9 are replaced as normal in the context name.

    The expiry time is counted from the point at which the context is created, so a context with a time of two minutes will be expired after two minutes regardless of when the last message was appended to it.

    If the optional when part of the rule is supplied, the specified action is taken and the context is removed when the context holds num entries.

    The autoappend keyword may be included to automatically create a subsequent append rule with the same regexps and context name.

match
    [in tags] regexp [not regexp] append name This appends a matching log entry to a context. If the context does not exist, this rule is silently ignored.

match
    [in tags] regexp [not regexp] close name action This applies the specified action and removes the context.

match
    [in tags] regexp [not regexp] clear name action This applies the specified action and clears all accumulated log entries from the context.

An example set of context rules is:

match in auth "sshd\\[([0-9]*)\\]: input_userauth_request: invalid user .*" open "sshd-$1" expire 2m pipe "/usr/bin/mail -s \"`date` ssh attempt (expired)\" root"

match in auth "sshd\\[([0-9]*)\\]: .*" append "sshd-$1"

match in auth "sshd\\[([0-9]*)\\]: Received disconnect from .*" close "sshd-$1" pipe "/usr/bin/mail -s \"`date` ssh attempt\" root"

The first rule opens the context named with the sshd pid, the second appends all messages from the same sshd pid (including the messages matching the open and close rules) to the context and the third rule closes and mails the context when the remote client disconnects.

FILES
/etc/logfmon.conf
    default logfmon(8) configuration file

SEE ALSO
re_format(7), logfmon(8)

AUTHORS
Nicholas Marriott <nicm@users.sourceforge.net>