log2mail.rb(1) -- monitors (log) files for patterns and reports hits by mail

log2mail.rb (start|stop|status|configtest) [options]:

log2mail.rb helps having an eye on your systems' log files. It efficiently monitors multiple files and reports as soon as specified (regular expression) patterns match.

On startup, log2mail.rb opens all files on the 'watch list' and seeks to EOF. All new data are parsed about once a minute (see --sleeptime). Matched patterns are reported to the configured mail address(es) (see mailto configuration option).

Log files are reopened automatically when rotated.

log2mail.rb is a pure ruby clone of log2mail which supports most of the original's features and configuration syntax and adds multiline regular expression matching. Actually it should be possible to use log2mail.rb with your existing configuration you may have for log2mail(8).

• --config=path, -c path: Specifies the configuration file or directory path. If path is a directory, all files (except such ending in ~ or #) are parsed in sorted order. Sorting is by character code, i.e. 0-9 before A-Z followed by a-z. Default value: /etc/log2mail/conf. This can also be set by environment variable LOG2MAIL_CONF.

• --sleeptime=seconds: Specifies at which interval (in seconds) the log files are parsed. Default value: 60.

log2mail.rb uses the environment variable LOG2MAIL_CONF, if present (see option --config). The value supplied by option takes precedence.

The old-style configuration syntax is directly cloned from log2mail(8)'s behavior and should be mostly compatible. It may seem a bit awkward first, but this is how it works: There are two possible top-level 'sections', defaults and file=path-to-log-file sections. The only statement allowed after a file=... section are one or more pattern=pattern entries. After the pattern=... there may be one or more mailto=single-mail-recipient entries. After each mailto=... there may be options for that recipient. Also, these options are set from the special defaults section, if present (usually it is).

The basic layout looks like follows:

# comments start with pound sign (aka hash or number sign)

defaults
  fromaddr   = DEFAULT FROMADDR
  sendtime   = DEFAULT SENDTIME   # seconds
  resendtime = DEFAULT RESENDTIME # seconds
  maxlines   = DEFAULT MAXLINES   # number of lines
  template   = DEFAULT TEMPLATE   # filename or path
  sendmail   = DEFAULT SENDMAIL   # path to executable with arguments
  mailto     = DEFAULT RECIPIENT  # new to log2mail.rb
  # awkward, not recommended, but possible:
  pattern    = DEFAULT PATTERN    # this pattern would be applied to every file
  mailto     = DEFAULT RECIPIENT for previous DEFAULT PATTERN

# one or more file sections follow
file = FILENAME

  # each file can have one or more patterns
  pattern = PATTERN

    # each pattern can have one or more mailto recipients
    # each recipient gets its own mailto=... statement
    mailto = MAIL

      # every option NOT stated here is supplied from defaults
      fromaddr   = ...
      sendtime   = ...
      resendtime = ...
      maxlines   = ...
      template   = ...
      sendmail   = ...

# "include" includes the contents of file at the exact place of the
# include statement
include = PATH TO FILE

Note that indentation is done for readability purposes only. It serves no role syntactically.

Splitting the configuration into multiple files is possible, and convenient when using automation tools to distribute settings. In opposition to classic log2mail, with log2mail.rb it does not matter at which place the defaults section is parsed. Keep in mind though, that later definitions may override earlier ones. In that case a warning is logged.

None (yet). More features might warrant a new configuration syntax.

It is neither necessary nor recommended to run this software as root.

Configuration options sendtime, resendtime, maxlines not implemented yet. Every match produces a single mail which is sent out immediately - which could produce a lot of mails.

December 2014: This software is not feature-complete and in pre-release testing.

Markus Strauss <log2mail@dev.sieb.mx>

Many thanks to Michael Krax for writing the classic log2mail in the first place.

Documentation for the classic log2mail software by Michael Krax:

• log2mail(8), log2mail.conf(5)
• Configuration notice from the Debian project