**************************
ommail: Mail Output Module
**************************

.. meta::
   :description: Send syslog messages as email alerts via the ommail output module.
   :keywords: rsyslog, ommail, mail output module, smtp, alerting, templates

.. summary-start

Ommail sends selected syslog messages as email alerts via SMTP or a
sendmail-compatible local submission program, with optional templates
for the subject and body.
.. summary-end

.. index:: ! imudp

===========================  ===========================================================================
**Module Name:**             **ommail**
**Available Since:**         **3.17.0**
**Author:**                  `Rainer Gerhards <https://rainer.gerhards.net/>`_ <rgerhards@adiscon.com>
===========================  ===========================================================================


Purpose
=======

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 assumed that mails will only be sent in an
extremely limited number of cases.

Ommail supports two delivery modes. The default ``smtp`` mode talks
directly to an SMTP server. The ``sendmail`` mode invokes a
sendmail-compatible binary, normally ``/usr/sbin/sendmail``, and writes
the generated message to its standard input.

Ommail uses up to two templates, one for the mail body and optionally
one for the subject line. Note that the subject line can also be set to
a constant text.
If neither the subject nor the mail body 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 

.. code-block:: none

  action.execonlyonceeveryinterval="<seconds>"

parameter 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

.. code-block:: none

  action.execonlyonceeveryinterval="7200"

in the action definition. Messages sent more frequently are simply discarded.


Configuration Parameters
========================

Configuration parameters are supported starting with v8.5.0. Earlier
v7 and v8 versions did only support legacy parameters.

.. note::

   Parameter names are case-insensitive; camelCase is recommended for readability.


Input Parameters
----------------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Parameter
     - Summary
   * - :ref:`param-ommail-mode`
     - .. include:: ../../reference/parameters/ommail-mode.rst
        :start-after: .. summary-start
        :end-before: .. summary-end
   * - :ref:`param-ommail-server`
     - .. include:: ../../reference/parameters/ommail-server.rst
        :start-after: .. summary-start
        :end-before: .. summary-end
   * - :ref:`param-ommail-port`
     - .. include:: ../../reference/parameters/ommail-port.rst
        :start-after: .. summary-start
        :end-before: .. summary-end
   * - :ref:`param-ommail-mailfrom`
     - .. include:: ../../reference/parameters/ommail-mailfrom.rst
        :start-after: .. summary-start
        :end-before: .. summary-end
   * - :ref:`param-ommail-mailto`
     - .. include:: ../../reference/parameters/ommail-mailto.rst
        :start-after: .. summary-start
        :end-before: .. summary-end
   * - :ref:`param-ommail-subject-template`
     - .. include:: ../../reference/parameters/ommail-subject-template.rst
        :start-after: .. summary-start
        :end-before: .. summary-end
   * - :ref:`param-ommail-subject-text`
     - .. include:: ../../reference/parameters/ommail-subject-text.rst
        :start-after: .. summary-start
        :end-before: .. summary-end
   * - :ref:`param-ommail-body-enable`
     - .. include:: ../../reference/parameters/ommail-body-enable.rst
        :start-after: .. summary-start
        :end-before: .. summary-end
   * - :ref:`param-ommail-template`
     - .. include:: ../../reference/parameters/ommail-template.rst
        :start-after: .. summary-start
        :end-before: .. summary-end
   * - :ref:`param-ommail-sendmail-binary`
     - .. include:: ../../reference/parameters/ommail-sendmail-binary.rst
        :start-after: .. summary-start
        :end-before: .. summary-end

.. toctree::
   :hidden:

   ../../reference/parameters/ommail-mode
   ../../reference/parameters/ommail-server
   ../../reference/parameters/ommail-port
   ../../reference/parameters/ommail-mailfrom
   ../../reference/parameters/ommail-mailto
   ../../reference/parameters/ommail-subject-template
   ../../reference/parameters/ommail-subject-text
   ../../reference/parameters/ommail-body-enable
   ../../reference/parameters/ommail-template
   ../../reference/parameters/ommail-sendmail-binary


Caveats/Known Bugs
==================

SMTP mode implements only the bare SMTP essentials. Most importantly,
it does not provide SMTP authentication capabilities. Your mail server
must be configured to accept incoming mail from ommail without
authentication, or you can use sendmail mode and let the local mail
submission program handle authentication and relay policy.

Sendmail mode depends on an external process. This can block while the
local submission program runs and is less directly controlled by
rsyslog than SMTP mode. Use a dedicated action queue if blocking is not
acceptable for your configuration.


Examples
========

Example 1
---------

The following example 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 (double backslashes are required in RainerScript string
literals). The ``body.enable="on"`` and ``template="mailBody"``
parameters bind the body
template to this action. A message is sent at most once every 6 hours
(21600 seconds), 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).

.. code-block:: none

   module(load="ommail")

   template (name="mailBody"  type="string" string="RSYSLOG Alert\\r\\nmsg='%msg%'")
   template (name="mailSubject" type="string" string="disk problem on %hostname%")

   if $msg contains "hard disk fatal failure" then {
      action(type="ommail" server="mail.example.net" port="25"
	     mailfrom="rsyslog@example.net"
	     mailto="operator@example.net"
	     body.enable="on" template="mailBody"
	     subject.template="mailSubject"
	     action.execonlyonceeveryinterval="21600")
   }


Example 2
---------

The following example is exactly like the first one, but it sends the mails
to two different email addresses:

.. code-block:: none

   module(load="ommail")

   template (name="mailBody"  type="string" string="RSYSLOG Alert\\r\\nmsg='%msg%'")
   template (name="mailSubject" type="string" string="disk problem on %hostname%")

   if $msg contains "hard disk fatal failure" then {
      action(type="ommail" server="mail.example.net" port="25"
	     mailfrom="rsyslog@example.net"
	     mailto=["operator@example.net", "admin@example.net"]
	     body.enable="on" template="mailBody"
	     subject.template="mailSubject"
	     action.execonlyonceeveryinterval="21600")
   }


Example 3
---------

Note the array syntax to specify email addresses. Note that while rsyslog
permits you to specify as many recipients as you like, your mail server
may limit their number. It is usually a bad idea to use more than 50
recipients, and some servers may have lower limits. If you hit such a limit,
you could either create additional actions or (recommended) create an
email distribution list.

The next example is again mostly equivalent to the previous one, but it uses a
constant subject line, so no subject template is required:

.. code-block:: none

   module(load="ommail")

   template (name="mailBody"  type="string" string="RSYSLOG Alert\\r\\nmsg='%msg%'")

   if $msg contains "hard disk fatal failure" then {
      action(type="ommail" server="mail.example.net" port="25"
	     mailfrom="rsyslog@example.net"
	     mailto=["operator@example.net", "admin@example.net"]
	     body.enable="on" template="mailBody"
	     subject.text="rsyslog detected disk problem"
	     action.execonlyonceeveryinterval="21600")
   }


Additional Resources
====================

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? <https://rainer.gerhards.net/2008/04/why-is-native-email-capability-an-advantage-for-a-syslogd.html>`_\ "
