Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix double quotes, add omprog send mail example #1007

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion source/configuration/modules/ommail.rst
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,10 @@ 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).
but you may also be referred to sendmail-mode). A suitable minimal
server ``msmtpd`` is part of `msmtp <https://marlam.de/msmtp/>`_
software and can be run locally to forward all the mail to a smart host
with support for TLS and authentication.

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
Expand All @@ -213,6 +216,9 @@ 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 (If
nobody does, sendmail mode will probably never be implemented).

Alternatively, consider using `omprog` as shown in
:ref:`omprog-example-msmtp`.


Examples
========
Expand Down
58 changes: 55 additions & 3 deletions source/configuration/modules/omprog.rst
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@ terminates, the program's stdin will see EOF. The program must then
terminate. The message format passed to the program can, as usual, be
modified by defining rsyslog templates.

If you need to invoke a program per every message, a wrapper can be
used, see :ref:`omprog-example-msmtp`.

Note that in order to execute the given program, rsyslog needs to have
sufficient permissions on the binary file. This is especially true if
not running as root. Also, keep in mind that default SELinux policies
Expand Down Expand Up @@ -84,10 +87,15 @@ binary

"string", "", "yes", "``$ActionOMProgBinary``"

Full path and command line parameters of the external program to execute.
Full path and command line parameters of the external program to execute. The
arguments are split on spaces; if you need to embed a space, add double quotes
to the very beginning and the end of the argument, at all other places the
double quotes symbol is passed as is.

Arbitrary external programs should be placed under the /usr/libexec/rsyslog directory.
That is, the binaries put in this namespaced directory are meant for the consumption
of rsyslog, and are not intended to be executed by users.

In legacy config, it is **not possible** to specify command line parameters.


Expand Down Expand Up @@ -472,14 +480,14 @@ Example: command line arguments

In the following example, logs will be sent to a program ``log.sh`` located
in ``/usr/libexec/rsyslog``. The program will receive the command line arguments
``p1``, ``p2`` and ``--param3="value 3"``.
``p1``, ``p2`` and ``--param3=value 3``.

.. code-block:: none

module(load="omprog")

action(type="omprog"
binary="/usr/libexec/rsyslog/log.sh p1 p2 --param3=\"value 3\""
binary="/usr/libexec/rsyslog/log.sh p1 p2 \"--param3=value 3\""
template="RSYSLOG_TraditionalFileFormat")


Expand Down Expand Up @@ -523,6 +531,50 @@ Note that the ``useTransactions`` flag is not used in this example. The
program stores and confirms each log individually.


.. _omprog-example-msmtp:

Example: sending mail to a smart host with authentication
---------------------------------------------------------

Here we rely on an additional POSIX shell script to execute a command per each
message.

.. code-block:: none

module(load="omprog")

template(name="mailData" type="string" string="Subject: disk problem on %hostname%\n\nRSYSLOG Alert\nmsg='%msg%'\n__RSYSLOG_ENDMSG__\n")

if $msg contains "hard disk fatal failure" then {
action(type="omprog"
binary="/usr/share/logging/omprog-dequeue.sh /usr/bin/msmtp --auth=on --tls=on --tls-starttls=on --host=mail.example.net --port=587 [email protected] \"--passwordeval=echo rsyslog-password\" [email protected] [email protected]"
template="mailData"
confirmMessages="on")
}

The ``omprog-dequeue.sh`` source:

.. code-block:: bash

#!/bin/sh

echo OK

while read -r line; do
if [ "$line" = "__RSYSLOG_ENDMSG__" ]; then
if echo "$msg" | "$@"; then
echo OK
else
echo ERROR
fi
msg=""
else
msg="${msg:+$msg
}$line"
fi
done


|FmtObsoleteName| directives
============================

Expand Down