mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-20 09:40:42 +01:00
129 lines
6.9 KiB
HTML
129 lines
6.9 KiB
HTML
<!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: ommail</b></p>
|
|
<p><b>Available since: </b> 3.17.0</p>
|
|
<p><b>Author: </b>Rainer Gerhards
|
|
<rgerhards@adiscon.com></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 "<span style="font-weight: bold;">$ActionExecOnlyOnceEveryInterval
|
|
<seconds></span>" 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.<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
|
|
<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).<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>
|
|
<p>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>
|