1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
<html><head><title>mail output module - sending syslog messages via mail</title>
6
<h1>Mail Output Module (ommail)</h1>
7
<p><b>Module Name: ommail</b></p>
8
<p><b>Available since: </b> 3.17.0</p>
9
<p><b>Author: </b>Rainer Gerhards
10
<rgerhards@adiscon.com></p>
11
<p><b>Description</b>:</p>
12
<p>This module supports sending syslog messages via mail. Each
13
syslog message is sent via its own mail. Obviously, you will want to
14
apply rigorous filtering, otherwise your mailbox (and mail server) will
15
be heavily spammed. The ommail plugin is primarily meant for alerting
16
users. As such, it is assume that mails will only be sent in an
17
extremely limited number of cases.</p>
18
<p>Please note that ommail is especially well-suited to work in
19
tandem with <a href="imfile.html">imfile</a> to
20
watch files for the occurence of specific things to be alerted on. So
21
its scope is far broader than forwarding syslog messages to mail
23
Ommail uses two templates, one for the mail body and one for the
24
subject line. If neither is provided, a quite meaningless subject line
25
is used and the mail body will be a syslog message just as if it were
26
written to a file. It is expected that the users customizes both
27
messages. In an effort to support cell phones (including SMS gateways),
28
there is an option to turn off the body part at all. This is considered
29
to be useful to send a short alert to a pager-like device.<br>
31
It is highly recommended to use the "<span style="font-weight: bold;">$ActionExecOnlyOnceEveryInterval
32
<seconds></span>" directive to limit the amount of
33
mails that potentially be generated. With it, mails are sent at most in
34
a <seconds> interval. This may be your life safer. And
35
remember that an hour has 3,600 seconds, so if you would like to
36
receive mails at most once every two hours, include a
37
"$ActionExecOnlyOnceEveryInterval 7200" immediately before the ommail
38
action. Messages sent more frequently are simpy discarded.<span style="font-weight: bold;"></span>
39
<p><b>Configuration Directives</b>:</p>
41
<li><span style="font-weight: bold;">$ActionMailSMTPServer</span><br>
42
Name or IP address of the SMTP server to be used. Must currently be
43
set. The default is 127.0.0.1, the SMTP server on the local machine.
44
Obviously it is not good to expect one to be present on each machine,
45
so this value should be specified.<br>
47
<li><span style="font-weight: bold;">$ActionMailSMTPPort</span><br>
48
Port number or name of the SMTP port to be used. The default is 25, the
49
standard SMTP port.</li>
50
<li><span style="font-weight: bold;">$ActionMailFrom</span><br>
51
The email address used as the senders address. There is no default.</li>
52
<li><span style="font-weight: bold;">$ActionMailTo</span><br>
53
The recipients email address. There is no default.</li>
54
<li><span style="font-weight: bold;">$ActionMailSubject</span><br>
55
The name of the <span style="font-weight: bold;">template</span>
56
to be used as the mail subject. If this is not specified, a more or
57
less meaningless mail subject is generated (we don't tell you the exact
58
text because that can change - if you want to have something specific,
60
<li><span style="font-weight: bold;">$ActionMailEnableBody</span><br>
61
Setting this to "off" permits to exclude the actual message body. This
62
may be useful for pager-like devices or cell phone SMS messages. The
63
default is "on", which is appropriate for allmost all cases. Turn it
64
off only if you know exactly what you do!</li>
66
<b>Caveats/Known Bugs:</b>
67
<p>The current ommail implementation supports <span style="font-weight: bold;">SMTP-direct mode</span>
68
only. In that mode, the plugin talks to the mail server via SMTP
69
protocol. No other process is involved. This mode offers best
70
reliability as it is not depending on any external entity except the
71
mail server. Mail server downtime is acceptable if the action is put
72
onto its own action queue, so that it may wait for the SMTP server to
73
come back online. However, the module implements only the bare SMTP
74
essentials. Most importantly, it does not provide any authentication
75
capabilities. So your mail server must be configured to accept incoming
76
mail from ommail without any authentication needs (this may be change
77
in the future as need arises, but you may also be referred to
79
<p>In theory, ommail should also offer a mode where it uses the
80
sendmail utility to send its mail (<span style="font-weight: bold;">sendmail-mode</span>).
81
This is somewhat less reliable (because we depend on an entity we do
82
not have close control over - sendmail). It also requires dramatically
83
more system ressources, as we need to load the external process (but
84
that should be no problem given the expected infrequent number of calls
85
into this plugin). The big advantage of sendmail mode is that it
86
supports all the bells and whistles of a full-blown SMTP implementation
87
and may even work for local delivery without a SMTP server being
88
present. Sendmail mode will be implemented as need arises. So if you
89
need it, please drop us a line (I nobody does, sendmail mode will
90
probably never be implemented).</p>
92
<p>The following sample alerts the operator if the string "hard
93
disk fatal failure" is present inside a syslog message. The mail server
94
at mail.example.net is used and the subject shall be "disk problem on
95
<hostname>". Note how \r\n is included inside the body
97
to create line breaks. A message is sent at most once every 6 hours,
98
any other messages are silently discarded (or, to be precise, not being
99
forwarded - they are still being processed by the rest of the
100
configuration file).<br>
102
<textarea rows="15" cols="80">$ModLoad ommail
103
$ActionMailSMTPServer mail.example.net
104
$ActionMailFrom rsyslog@example.net
105
$ActionMailTo operator@example.net
106
$template mailSubject,"disk problem on %hostname%"
107
$template mailBody,"RSYSLOG Alert\r\nmsg='%msg%'"
108
$ActionMailSubject mailSubject
109
# make sure we receive a mail only once in six
110
# hours (21,600 seconds ;))
111
$ActionExecOnlyOnceEveryInterval 21600
112
# the if ... then ... mailBody mus be on one line!
113
if $msg contains 'hard disk fatal failure' then :ommail:;mailBody
115
<p>A more advanced example plus a discussion on using the email feature
116
inside a reliable system can be found in Rainer's blogpost
117
"<a style="font-style: italic;" href="http://rgerhards.blogspot.com/2008/04/why-is-native-email-capability.html">Why
118
is native email capability an advantage for a syslogd?</a>"
119
<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>]
120
[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
121
<p><font size="2">This documentation is part of the
122
<a href="http://www.rsyslog.com/">rsyslog</a>
124
Copyright © 2008 by <a href="http://www.gerhards.net/rainer">Rainer
126
<a href="http://www.adiscon.com/">Adiscon</a>.
127
Released under the GNU GPL version 3 or higher.</font></p>
added
removed
doc/ommail.html
