From 9584c81df387adcdcd7b84078eda48092049101d Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Thu, 10 Apr 2008 08:06:48 +0200 Subject: added ommail.html - I forgot to add this file... --- doc/ommail.html | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 doc/ommail.html (limited to 'doc/ommail.html') diff --git a/doc/ommail.html b/doc/ommail.html new file mode 100644 index 00000000..b6b7c2ad --- /dev/null +++ b/doc/ommail.html @@ -0,0 +1,128 @@ + +mail output module - sending syslog messages via mail + + + +

Mail Output Module (ommail)

+

Module Name:    ommail

+

Author: Rainer Gerhards +<rgerhards@adiscon.com>

+

Description:

+

This module supports sending syslog messages via mail. Each +syslog message is sent via its own mail. Obviously, you will want to +apply rigorous filtering, otherwise your mailbox (and mail server) will +be heavily spammed. The ommail plugin is primarily meant for alerting +users. As such, it is assume that mails will only be sent in an +extremely limited number of cases.

+

Please note that ommail is especially well-suited to work in +tandem with imfile to +watch files for the occurence of specific things to be alerted on. So +its scope is far broader than forwarding syslog messages to mail +recipients.

+Ommail uses two templates, one for the mail body and one for the +subject line. If neither is provided, a quite meaningless subject line +is used and the mail body will be a syslog message just as if it were +written to a file. It is expected that the users customizes both +messages. In an effort to support cell phones (including SMS gateways), +there is an option to turn off the body part at all. This is considered +to be useful to send a short alert to a pager-like device.
+
+It is highly recommended to use the  "$ActionExecOnlyOnceEveryInterval +<seconds>" directive to limit the amount of +mails that potentially be generated. With it, mails are sent at most in +a <seconds> interval. This may be your life safer. And +remember that an hour has 3,600 seconds, so if you would like to +receive mails at most once every two hours, include a +"$ActionExecOnlyOnceEveryInterval 7200" immediately before the ommail +action. Messages sent more frequently are simpy discarded. +

Configuration Directives:

+ +Caveats/Known Bugs: +

The current ommail implementation supports SMTP-direct mode +only. In that mode, the plugin talks to the mail server via SMTP +protocol. No other process is involved. This mode offers best +reliability as it is not depending on any external entity except the +mail server. Mail server downtime is acceptable if the action is put +onto its own action queue, so that it may wait for the SMTP server to +come back online. However, the module implements only the bare SMTP +essentials. Most importantly, it does not provide any authentication +capabilities. So your mail server must be configured to accept incoming +mail from ommail without any authentication needs (this may be change +in the future as need arises, but you may also be referred to +sendmail-mode).

+

In theory, ommail should also offer a mode where it uses the +sendmail utility to send its mail (sendmail-mode). +This is somewhat less reliable (because we depend on an entity we do +not have close control over - sendmail). It also requires dramatically +more system ressources, as we need to load the external process (but +that should be no problem given the expected infrequent number of calls +into this plugin). The big advantage of sendmail mode is that it +supports all the bells and whistles of a full-blown SMTP implementation +and may even work for local delivery without a SMTP server being +present. Sendmail mode will be implemented as need arises. So if you +need it, please drop us a line (I nobody does, sendmail mode will +probably never be implemented).

+

Sample:

+

The following sample alerts the operator if the string "hard +disk fatal failure" is present inside a syslog message. The mail server +at mail.example.net is used and the subject shall be "disk problem on +<hostname>". Note how \r\n is included inside the body +text +to create line breaks. A message is sent at most once every 6 hours, +any other messages are silently discarded (or, to be precise, not being +forwarded - they are still being processed by the rest of the +configuration file).
+

+
+
+A more advanced example plus a discussion on using the email feature +inside a reliable system can be found in Rainer's blogpost +"Why +is native email capability an advantage for a syslogd?" +

[rsyslog.conf overview] +[manual index] [rsyslog site]

+

This documentation is part of the +rsyslog +project.
+Copyright © 2008 by Rainer +Gerhards and +Adiscon. +Released under the GNU GPL version 3 or higher.

+ \ No newline at end of file -- cgit