summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorRainer Gerhards <rgerhards@adiscon.com>2008-04-10 08:06:48 +0200
committerRainer Gerhards <rgerhards@adiscon.com>2008-04-10 08:06:48 +0200
commit9584c81df387adcdcd7b84078eda48092049101d (patch)
treec4a6f8f5763391925af02fb703525a7f6b9d0695 /doc
parent0f3dbecb867bc8ed852389ae9642be5d0f3636aa (diff)
downloadrsyslog-9584c81df387adcdcd7b84078eda48092049101d.tar.gz
rsyslog-9584c81df387adcdcd7b84078eda48092049101d.tar.xz
rsyslog-9584c81df387adcdcd7b84078eda48092049101d.zip
added ommail.html - I forgot to add this file...
Diffstat (limited to 'doc')
-rw-r--r--doc/ommail.html128
1 files changed, 128 insertions, 0 deletions
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 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head><title>mail output module - sending syslog messages via mail</title>
+
+</head>
+<body>
+<h1>Mail Output Module (ommail)</h1>
+<p><b>Module Name:&nbsp;&nbsp;&nbsp; ommail</b></p>
+<p><b>Author: </b>Rainer Gerhards
+&lt;rgerhards@adiscon.com&gt;</p>
+<p><b>Description</b>:</p>
+<p>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.</p>
+<p>Please note that ommail is especially well-suited to work in
+tandem with <a href="imfile.html">imfile</a> 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.</p>
+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.<br>
+<br>
+It is highly recommended to use the&nbsp; "<span style="font-weight: bold;">$ActionExecOnlyOnceEveryInterval
+&lt;seconds&gt;</span>" directive to limit the amount of
+mails that potentially be generated. With it, mails are sent at most in
+a &lt;seconds&gt; 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.<span style="font-weight: bold;"></span>
+<p><b>Configuration Directives</b>:</p>
+<ul>
+<li><span style="font-weight: bold;">$ActionMailSMTPServer</span><br>
+Name or IP address of the SMTP server to be used. Must currently be
+set. The default is 127.0.0.1, the SMTP server on the local machine.
+Obviously it is not good to expect one to be present on each machine,
+so this value should be specified.<br>
+</li>
+<li><span style="font-weight: bold;">$ActionMailSMTPPort</span><br>
+Port number or name of the SMTP port to be used. The default is 25, the
+standard SMTP port.</li>
+<li><span style="font-weight: bold;">$ActionMailFrom</span><br>
+The email address used as the senders address. There is no default.</li>
+<li><span style="font-weight: bold;">$ActionMailTo</span><br>
+The recipients email address. There is no default.</li>
+<li><span style="font-weight: bold;">$ActionMailSubject</span><br>
+The name of the <span style="font-weight: bold;">template</span>
+to be used as the mail subject. If this is not specified, a more or
+less meaningless mail subject is generated (we don't tell you the exact
+text because that can change - if you want to have something specific,
+configure it!).</li>
+<li><span style="font-weight: bold;">$ActionMailEnableBody</span><br>
+Setting this to "off" permits to exclude the actual message body. This
+may be useful for pager-like devices or cell phone SMS messages. The
+default is "on", which is appropriate for allmost all cases. Turn it
+off only if you know exactly what you do!</li>
+</ul>
+<b>Caveats/Known Bugs:</b>
+<p>The current ommail implementation supports <span style="font-weight: bold;">SMTP-direct mode</span>
+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).</p>
+<p>In theory, ommail should also offer a mode where it uses the
+sendmail utility to send its mail (<span style="font-weight: bold;">sendmail-mode</span>).
+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).</p>
+<p><b>Sample:</b></p>
+<p>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
+&lt;hostname&gt;". 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).<br>
+</p>
+<textarea rows="15" cols="80">$ModLoad ommail
+$ActionMailSMTPServer mail.example.net
+$ActionMailFrom rsyslog@example.net
+$ActionMailTo operator@example.net
+$template mailSubject,"disk problem on %hostname%"
+$template mailBody,"RSYSLOG Alert\r\nmsg='%msg%'"
+$ActionMailSubject mailSubject
+# make sure we receive a mail only once in six
+# hours (21,600 seconds ;))
+$ActionExecOnlyOnceEveryInterval 21600
+# the if ... then ... mailBody mus be on one line!
+if $msg contains 'hard disk fatal failure' then :ommail:;mailBody
+</textarea><br>
+<br>
+A more advanced example plus a discussion on using the email feature
+inside a reliable system can be found in Rainer's blogpost
+"<a style="font-style: italic;" href="http://rgerhards.blogspot.com/2008/04/why-is-native-email-capability.html">Why
+is native email capability an advantage for a syslogd?</a>"
+<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>]
+[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
+<p><font size="2">This documentation is part of the
+<a href="http://www.rsyslog.com/">rsyslog</a>
+project.<br>
+Copyright © 2008 by <a href="http://www.gerhards.net/rainer">Rainer
+Gerhards</a> and
+<a href="http://www.adiscon.com/">Adiscon</a>.
+Released under the GNU GPL version 3 or higher.</font></p>
+</body></html> \ No newline at end of file