Fix double quotes, add omprog send mail example

source/configuration/modules/ommail.rst

@@ -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
@@ -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
 ========

source/configuration/modules/omprog.rst

@@ -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
@@ -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.
 
 
@@ -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")
 
 
@@ -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
 ============================