omprog: add example script to run an app for each message

This adds a simple POSIX shell script that can be used to execute an
program for every log message (as the legacy ^ action).

Since the example shows how to use it to send mail, a reference is added
to the ommail page too.

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