mirror of
https://github.com/rsyslog/rsyslog.git
synced 2026-06-20 02:52:56 +02:00
Merge pull request #5985 from rsyslog/codex/refactor-rsyslog-parameters-documentation
omprog: split parameter docs into reference pages
This commit is contained in:
Rainer Gerhards
GitHub
commit
a653e30ae0
@ -54,415 +54,96 @@ Configuration Parameters
|
|||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
Parameter names are case-insensitive.
|
Parameter names are case-insensitive; camelCase is recommended for readability.
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:hidden:
|
||||||
|
|
||||||
|
../../reference/parameters/omprog-template
|
||||||
|
../../reference/parameters/omprog-binary
|
||||||
|
../../reference/parameters/omprog-confirmmessages
|
||||||
|
../../reference/parameters/omprog-confirmtimeout
|
||||||
|
../../reference/parameters/omprog-reportfailures
|
||||||
|
../../reference/parameters/omprog-usetransactions
|
||||||
|
../../reference/parameters/omprog-begintransactionmark
|
||||||
|
../../reference/parameters/omprog-committransactionmark
|
||||||
|
../../reference/parameters/omprog-output
|
||||||
|
../../reference/parameters/omprog-filecreatemode
|
||||||
|
../../reference/parameters/omprog-hup-signal
|
||||||
|
../../reference/parameters/omprog-signalonclose
|
||||||
|
../../reference/parameters/omprog-closetimeout
|
||||||
|
../../reference/parameters/omprog-killunresponsive
|
||||||
|
../../reference/parameters/omprog-forcesingleinstance
|
||||||
|
|
||||||
Action Parameters
|
Action Parameters
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
template
|
.. list-table::
|
||||||
^^^^^^^^
|
:widths: 30 70
|
||||||
|
:header-rows: 1
|
||||||
.. csv-table::
|
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
* - Parameter
|
||||||
:widths: auto
|
- Summary
|
||||||
:class: parameter-table
|
* - :ref:`param-omprog-template`
|
||||||
|
- .. include:: ../../reference/parameters/omprog-template.rst
|
||||||
"word", "RSYSLOG_FileFormat", "no", "none"
|
:start-after: .. summary-start
|
||||||
|
:end-before: .. summary-end
|
||||||
Name of the :doc:`template <../templates>` to use to format the log messages
|
* - :ref:`param-omprog-binary`
|
||||||
passed to the external program.
|
- .. include:: ../../reference/parameters/omprog-binary.rst
|
||||||
|
:start-after: .. summary-start
|
||||||
|
:end-before: .. summary-end
|
||||||
binary
|
* - :ref:`param-omprog-confirmmessages`
|
||||||
^^^^^^
|
- .. include:: ../../reference/parameters/omprog-confirmmessages.rst
|
||||||
|
:start-after: .. summary-start
|
||||||
.. csv-table::
|
:end-before: .. summary-end
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
* - :ref:`param-omprog-confirmtimeout`
|
||||||
:widths: auto
|
- .. include:: ../../reference/parameters/omprog-confirmtimeout.rst
|
||||||
:class: parameter-table
|
:start-after: .. summary-start
|
||||||
|
:end-before: .. summary-end
|
||||||
"string", "", "yes", "``$ActionOMProgBinary``"
|
* - :ref:`param-omprog-reportfailures`
|
||||||
|
- .. include:: ../../reference/parameters/omprog-reportfailures.rst
|
||||||
Full path and command line parameters of the external program to execute.
|
:start-after: .. summary-start
|
||||||
Arbitrary external programs should be placed under the /usr/libexec/rsyslog directory.
|
:end-before: .. summary-end
|
||||||
That is, the binaries put in this namespaced directory are meant for the consumption
|
* - :ref:`param-omprog-usetransactions`
|
||||||
of rsyslog, and are not intended to be executed by users.
|
- .. include:: ../../reference/parameters/omprog-usetransactions.rst
|
||||||
In legacy config, it is **not possible** to specify command line parameters.
|
:start-after: .. summary-start
|
||||||
|
:end-before: .. summary-end
|
||||||
|
* - :ref:`param-omprog-begintransactionmark`
|
||||||
.. _confirmMessages:
|
- .. include:: ../../reference/parameters/omprog-begintransactionmark.rst
|
||||||
|
:start-after: .. summary-start
|
||||||
confirmMessages
|
:end-before: .. summary-end
|
||||||
^^^^^^^^^^^^^^^
|
* - :ref:`param-omprog-committransactionmark`
|
||||||
|
- .. include:: ../../reference/parameters/omprog-committransactionmark.rst
|
||||||
.. csv-table::
|
:start-after: .. summary-start
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
:end-before: .. summary-end
|
||||||
:widths: auto
|
* - :ref:`param-omprog-output`
|
||||||
:class: parameter-table
|
- .. include:: ../../reference/parameters/omprog-output.rst
|
||||||
|
:start-after: .. summary-start
|
||||||
"binary", "off", "no", "none"
|
:end-before: .. summary-end
|
||||||
|
* - :ref:`param-omprog-filecreatemode`
|
||||||
.. versionadded:: 8.31.0
|
- .. include:: ../../reference/parameters/omprog-filecreatemode.rst
|
||||||
|
:start-after: .. summary-start
|
||||||
Specifies whether the external program provides feedback to rsyslog via stdout.
|
:end-before: .. summary-end
|
||||||
When this switch is set to "on", rsyslog will wait for the program to confirm
|
* - :ref:`param-omprog-hup-signal`
|
||||||
each received message. This feature facilitates error handling: instead of
|
- .. include:: ../../reference/parameters/omprog-hup-signal.rst
|
||||||
having to implement a retry logic, the external program can rely on the rsyslog
|
:start-after: .. summary-start
|
||||||
queueing capabilities.
|
:end-before: .. summary-end
|
||||||
|
* - :ref:`param-omprog-signalonclose`
|
||||||
To confirm a message, the program must write a line with the word ``OK`` to its
|
- .. include:: ../../reference/parameters/omprog-signalonclose.rst
|
||||||
standard output. If it writes a line containing anything else, rsyslog considers
|
:start-after: .. summary-start
|
||||||
that the message could not be processed, keeps it in the action queue, and
|
:end-before: .. summary-end
|
||||||
re-sends it to the program later (after the period specified by the
|
* - :ref:`param-omprog-closetimeout`
|
||||||
:doc:`action.resumeInterval <../actions>` parameter).
|
- .. include:: ../../reference/parameters/omprog-closetimeout.rst
|
||||||
|
:start-after: .. summary-start
|
||||||
In addition, when a new instance of the program is started, rsyslog will also
|
:end-before: .. summary-end
|
||||||
wait for the program to confirm it is ready to start consuming logs. This
|
* - :ref:`param-omprog-killunresponsive`
|
||||||
prevents rsyslog from starting to send logs to a program that could not
|
- .. include:: ../../reference/parameters/omprog-killunresponsive.rst
|
||||||
complete its initialization properly.
|
:start-after: .. summary-start
|
||||||
|
:end-before: .. summary-end
|
||||||
.. seealso::
|
* - :ref:`param-omprog-forcesingleinstance`
|
||||||
|
- .. include:: ../../reference/parameters/omprog-forcesingleinstance.rst
|
||||||
`Interface between rsyslog and external output plugins
|
:start-after: .. summary-start
|
||||||
<https://github.com/rsyslog/rsyslog/blob/master/plugins/external/INTERFACE.md>`_
|
:end-before: .. summary-end
|
||||||
|
|
||||||
|
|
||||||
.. _confirmTimeout:
|
|
||||||
|
|
||||||
confirmTimeout
|
|
||||||
^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
.. csv-table::
|
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
|
||||||
:widths: auto
|
|
||||||
:class: parameter-table
|
|
||||||
|
|
||||||
"integer", "10000", "no", "none"
|
|
||||||
|
|
||||||
.. versionadded:: 8.38.0
|
|
||||||
|
|
||||||
Specifies how long rsyslog must wait for the external program to confirm
|
|
||||||
each message when confirmMessages_ is set to "on". If the program does not
|
|
||||||
send a response within this timeout, it will be restarted (see signalOnClose_,
|
|
||||||
closeTimeout_ and killUnresponsive_ for details on the cleanup sequence).
|
|
||||||
The value must be expressed in milliseconds and must be greater than zero.
|
|
||||||
|
|
||||||
.. seealso::
|
|
||||||
|
|
||||||
`Interface between rsyslog and external output plugins
|
|
||||||
<https://github.com/rsyslog/rsyslog/blob/master/plugins/external/INTERFACE.md>`_
|
|
||||||
|
|
||||||
|
|
||||||
.. _reportFailures:
|
|
||||||
|
|
||||||
reportFailures
|
|
||||||
^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
.. csv-table::
|
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
|
||||||
:widths: auto
|
|
||||||
:class: parameter-table
|
|
||||||
|
|
||||||
"binary", "off", "no", "none"
|
|
||||||
|
|
||||||
.. versionadded:: 8.38.0
|
|
||||||
|
|
||||||
Specifies whether rsyslog must internally log a warning message whenever the
|
|
||||||
program returns an error when confirming a message. The logged message will
|
|
||||||
include the error line returned by the program. This parameter is ignored when
|
|
||||||
confirmMessages_ is set to "off".
|
|
||||||
|
|
||||||
Enabling this flag can be useful to log the problems detected by the program.
|
|
||||||
However, the information that can be logged is limited to a short error line,
|
|
||||||
and the logs will be tagged as originated by the 'syslog' facility (like the
|
|
||||||
rest of rsyslog logs). To avoid these shortcomings, consider the use of the
|
|
||||||
output_ parameter to capture the stderr of the program.
|
|
||||||
|
|
||||||
|
|
||||||
.. _useTransactions:
|
|
||||||
|
|
||||||
useTransactions
|
|
||||||
^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
.. csv-table::
|
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
|
||||||
:widths: auto
|
|
||||||
:class: parameter-table
|
|
||||||
|
|
||||||
"binary", "off", "no", "none"
|
|
||||||
|
|
||||||
.. versionadded:: 8.31.0
|
|
||||||
|
|
||||||
Specifies whether the external program processes the messages in
|
|
||||||
:doc:`batches <../../development/dev_oplugins>` (transactions). When this
|
|
||||||
switch is enabled, the logs sent to the program are grouped in transactions.
|
|
||||||
At the start of a transaction, rsyslog sends a special mark message to the
|
|
||||||
program (see beginTransactionMark_). At the end of the transaction, rsyslog
|
|
||||||
sends another mark message (see commitTransactionMark_).
|
|
||||||
|
|
||||||
If confirmMessages_ is also set to "on", the program must confirm both the
|
|
||||||
mark messages and the logs within the transaction. The mark messages must be
|
|
||||||
confirmed by returning ``OK``, and the individual messages by returning
|
|
||||||
``DEFER_COMMIT`` (instead of ``OK``). Refer to the link below for details.
|
|
||||||
|
|
||||||
.. seealso::
|
|
||||||
|
|
||||||
`Interface between rsyslog and external output plugins
|
|
||||||
<https://github.com/rsyslog/rsyslog/blob/master/plugins/external/INTERFACE.md>`_
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
This feature is currently **experimental**. It could change in future releases
|
|
||||||
without keeping backwards compatibility with existing configurations or the
|
|
||||||
specified interface. There is also a `known issue
|
|
||||||
<https://github.com/rsyslog/rsyslog/issues/2420>`_ with the use of
|
|
||||||
transactions together with ``confirmMessages=on``.
|
|
||||||
|
|
||||||
|
|
||||||
.. _beginTransactionMark:
|
|
||||||
|
|
||||||
beginTransactionMark
|
|
||||||
^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
.. csv-table::
|
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
|
||||||
:widths: auto
|
|
||||||
:class: parameter-table
|
|
||||||
|
|
||||||
"string", "BEGIN TRANSACTION", "no", "none"
|
|
||||||
|
|
||||||
.. versionadded:: 8.31.0
|
|
||||||
|
|
||||||
Allows specifying the mark message that rsyslog will send to the external
|
|
||||||
program to indicate the start of a transaction (batch). This parameter is
|
|
||||||
ignored if useTransactions_ is disabled.
|
|
||||||
|
|
||||||
|
|
||||||
.. _commitTransactionMark:
|
|
||||||
|
|
||||||
commitTransactionMark
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
.. csv-table::
|
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
|
||||||
:widths: auto
|
|
||||||
:class: parameter-table
|
|
||||||
|
|
||||||
"string", "COMMIT TRANSACTION", "no", "none"
|
|
||||||
|
|
||||||
.. versionadded:: 8.31.0
|
|
||||||
|
|
||||||
Allows specifying the mark message that rsyslog will send to the external
|
|
||||||
program to indicate the end of a transaction (batch). This parameter is
|
|
||||||
ignored if useTransactions_ is disabled.
|
|
||||||
|
|
||||||
|
|
||||||
.. _output:
|
|
||||||
|
|
||||||
output
|
|
||||||
^^^^^^
|
|
||||||
|
|
||||||
.. csv-table::
|
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
|
||||||
:widths: auto
|
|
||||||
:class: parameter-table
|
|
||||||
|
|
||||||
"string", "none", "no", "none"
|
|
||||||
|
|
||||||
.. versionadded:: v8.1.6
|
|
||||||
|
|
||||||
Full path of a file where the output of the external program will be saved.
|
|
||||||
If the file already exists, the output is appended to it. If the file does
|
|
||||||
not exist, it is created with the permissions specified by fileCreateMode_.
|
|
||||||
|
|
||||||
If confirmMessages_ is set to "off" (the default), both the stdout and
|
|
||||||
stderr of the child process are written to the specified file.
|
|
||||||
|
|
||||||
If confirmMessages_ is set to "on", only the stderr of the child is
|
|
||||||
written to the specified file (since stdout is used for confirming the
|
|
||||||
messages).
|
|
||||||
|
|
||||||
Rsyslog will reopen the file whenever it receives a HUP signal. This allows
|
|
||||||
the file to be externally rotated (using a tool like *logrotate*): after
|
|
||||||
each rotation of the file, make sure a HUP signal is sent to rsyslogd.
|
|
||||||
|
|
||||||
If the omprog action is configured to use multiple worker threads
|
|
||||||
(:doc:`queue.workerThreads <../../rainerscript/queue_parameters>` is
|
|
||||||
set to a value greater than 1), the lines written by the various program
|
|
||||||
instances will not appear intermingled in the output file, as long as the
|
|
||||||
lines do not exceed a certain length and the program writes them to
|
|
||||||
stdout/stderr in line-buffered mode. For details, refer to `Interface between
|
|
||||||
rsyslog and external output plugins
|
|
||||||
<https://github.com/rsyslog/rsyslog/blob/master/plugins/external/INTERFACE.md>`_.
|
|
||||||
|
|
||||||
If this parameter is not specified, the output of the program will be
|
|
||||||
redirected to ``/dev/null``.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
Before version v8.38.0, this parameter was intended for debugging purposes
|
|
||||||
only. Since v8.38.0, the parameter can be used for production.
|
|
||||||
|
|
||||||
|
|
||||||
.. _fileCreateMode:
|
|
||||||
|
|
||||||
fileCreateMode
|
|
||||||
^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
.. csv-table::
|
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
|
||||||
:widths: auto
|
|
||||||
:class: parameter-table
|
|
||||||
|
|
||||||
"string", "0600", "no", "none"
|
|
||||||
|
|
||||||
.. versionadded:: v8.38.0
|
|
||||||
|
|
||||||
Permissions the output_ file will be created with, in case the file does not
|
|
||||||
exist. The value must be a 4-digit octal number, with the initial digit being
|
|
||||||
zero. Please note that the actual permission depends on the rsyslogd process
|
|
||||||
umask. If in doubt, use ``$umask 0000`` right at the beginning of the
|
|
||||||
configuration file to remove any restrictions.
|
|
||||||
|
|
||||||
|
|
||||||
hup.signal
|
|
||||||
^^^^^^^^^^
|
|
||||||
|
|
||||||
.. csv-table::
|
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
|
||||||
:widths: auto
|
|
||||||
:class: parameter-table
|
|
||||||
|
|
||||||
"word", "none", "no", "none"
|
|
||||||
|
|
||||||
.. versionadded:: 8.9.0
|
|
||||||
|
|
||||||
Specifies which signal, if any, is to be forwarded to the external program
|
|
||||||
when rsyslog receives a HUP signal. Currently, HUP, USR1, USR2, INT, and
|
|
||||||
TERM are supported. If unset, no signal is sent on HUP. This is the default
|
|
||||||
and what pre 8.9.0 versions did.
|
|
||||||
|
|
||||||
|
|
||||||
.. _signalOnClose:
|
|
||||||
|
|
||||||
signalOnClose
|
|
||||||
^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
.. csv-table::
|
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
|
||||||
:widths: auto
|
|
||||||
:class: parameter-table
|
|
||||||
|
|
||||||
"binary", "off", "no", "none"
|
|
||||||
|
|
||||||
.. versionadded:: 8.23.0
|
|
||||||
|
|
||||||
Specifies whether a TERM signal must be sent to the external program before
|
|
||||||
closing it (when either the worker thread has been unscheduled, a restart
|
|
||||||
of the program is being forced, or rsyslog is about to shutdown).
|
|
||||||
|
|
||||||
If this switch is set to "on", rsyslog will send a TERM signal to the child
|
|
||||||
process before closing the pipe. That is, the process will first receive a
|
|
||||||
TERM signal, and then an EOF on stdin.
|
|
||||||
|
|
||||||
No signal is issued if this switch is set to "off" (default). The child
|
|
||||||
process can still detect it must terminate because reading from stdin will
|
|
||||||
return EOF.
|
|
||||||
|
|
||||||
See the killUnresponsive_ parameter for more details.
|
|
||||||
|
|
||||||
|
|
||||||
.. _closeTimeout:
|
|
||||||
|
|
||||||
closeTimeout
|
|
||||||
^^^^^^^^^^^^
|
|
||||||
|
|
||||||
.. csv-table::
|
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
|
||||||
:widths: auto
|
|
||||||
:class: parameter-table
|
|
||||||
|
|
||||||
"integer", "5000", "no", "none"
|
|
||||||
|
|
||||||
.. versionadded:: 8.35.0
|
|
||||||
|
|
||||||
Specifies how long rsyslog must wait for the external program to terminate
|
|
||||||
(when either the worker thread has been unscheduled, a restart of the program
|
|
||||||
is being forced, or rsyslog is about to shutdown) after closing the pipe,
|
|
||||||
that is, after sending EOF to the stdin of the child process. The value must
|
|
||||||
be expressed in milliseconds and must be greater than or equal to zero.
|
|
||||||
|
|
||||||
See the killUnresponsive_ parameter for more details.
|
|
||||||
|
|
||||||
|
|
||||||
.. _killUnresponsive:
|
|
||||||
|
|
||||||
killUnresponsive
|
|
||||||
^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
.. csv-table::
|
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
|
||||||
:widths: auto
|
|
||||||
:class: parameter-table
|
|
||||||
|
|
||||||
"binary", "the value of 'signalOnClose'", "no", "none"
|
|
||||||
|
|
||||||
.. versionadded:: 8.35.0
|
|
||||||
|
|
||||||
Specifies whether a KILL signal must be sent to the external program in case
|
|
||||||
it does not terminate within the timeout indicated by closeTimeout_
|
|
||||||
(when either the worker thread has been unscheduled, a restart of the program
|
|
||||||
is being forced, or rsyslog is about to shutdown).
|
|
||||||
|
|
||||||
If signalOnClose_ is set to "on", the default value of ``killUnresponsive``
|
|
||||||
is also "on". In this case, the cleanup sequence of the child process is as
|
|
||||||
follows: (1) a TERM signal is sent to the child, (2) the pipe with the child
|
|
||||||
process is closed (the child will receive EOF on stdin), (3) rsyslog waits
|
|
||||||
for the child process to terminate during closeTimeout_, (4) if the child
|
|
||||||
has not terminated within the timeout, a KILL signal is sent to it.
|
|
||||||
|
|
||||||
If signalOnClose_ is set to "off", the default value of ``killUnresponsive``
|
|
||||||
is also "off". In this case, the child cleanup sequence is as follows: (1) the
|
|
||||||
pipe with the child process is closed (the child will receive EOF on stdin),
|
|
||||||
(2) rsyslog waits for the child process to terminate during closeTimeout_,
|
|
||||||
(3) if the child has not terminated within the timeout, rsyslog ignores it.
|
|
||||||
|
|
||||||
This parameter can be set to a different value than signalOnClose_, obtaining
|
|
||||||
the corresponding variations of cleanup sequences described above.
|
|
||||||
|
|
||||||
|
|
||||||
forceSingleInstance
|
|
||||||
^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
.. csv-table::
|
|
||||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
|
||||||
:widths: auto
|
|
||||||
:class: parameter-table
|
|
||||||
|
|
||||||
"binary", "off", "no", "none"
|
|
||||||
|
|
||||||
.. versionadded:: v8.1.6
|
|
||||||
|
|
||||||
By default, the omprog action will start an instance (process) of the
|
|
||||||
external program per worker thread (the maximum number of worker threads
|
|
||||||
can be specified with the
|
|
||||||
:doc:`queue.workerThreads <../../rainerscript/queue_parameters>`
|
|
||||||
parameter). Moreover, if the action is associated to a
|
|
||||||
:doc:`disk-assisted queue <../../concepts/queues>`, an additional instance
|
|
||||||
will be started when the queue is persisted, to process the items stored
|
|
||||||
on disk.
|
|
||||||
|
|
||||||
If you want to force a single instance of the program to be executed,
|
|
||||||
regardless of the number of worker threads or the queue type, set this
|
|
||||||
flag to "on". This is useful when the external program uses or accesses
|
|
||||||
some kind of shared resource that does not allow concurrent access from
|
|
||||||
multiple processes.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
Before version v8.38.0, this parameter had no effect.
|
|
||||||
|
|
||||||
|
|
||||||
Examples
|
Examples
|
||||||
========
|
========
|
||||||
@ -523,8 +204,3 @@ Note that the ``useTransactions`` flag is not used in this example. The
|
|||||||
program stores and confirms each log individually.
|
program stores and confirms each log individually.
|
||||||
|
|
||||||
|
|
||||||
|FmtObsoleteName| directives
|
|
||||||
============================
|
|
||||||
|
|
||||||
- **$ActionOMProgBinary** <binary>
|
|
||||||
The binary program to be executed.
|
|
||||||
|
|||||||
@ -0,0 +1,45 @@
|
|||||||
|
.. _param-omprog-begintransactionmark:
|
||||||
|
.. _omprog.parameter.action.begintransactionmark:
|
||||||
|
|
||||||
|
beginTransactionMark
|
||||||
|
=====================
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; beginTransactionMark
|
||||||
|
single: beginTransactionMark
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Defines the marker sent to denote the start of a transaction.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: beginTransactionMark
|
||||||
|
:Scope: action
|
||||||
|
:Type: string
|
||||||
|
:Default: action="BEGIN TRANSACTION"
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: 8.31.0
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Allows specifying the mark message that rsyslog will send to the external
|
||||||
|
program to indicate the start of a transaction (batch). This parameter is
|
||||||
|
ignored if :ref:`param-omprog-usetransactions` is disabled.
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-begintransactionmark:
|
||||||
|
.. _omprog.parameter.action.begintransactionmark-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog"
|
||||||
|
useTransactions="on"
|
||||||
|
beginTransactionMark="BEGIN TRANSACTION")
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
57
doc/source/reference/parameters/omprog-binary.rst
Normal file
57
doc/source/reference/parameters/omprog-binary.rst
Normal file
@ -0,0 +1,57 @@
|
|||||||
|
.. _param-omprog-binary:
|
||||||
|
.. _omprog.parameter.action.binary:
|
||||||
|
|
||||||
|
binary
|
||||||
|
======
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; binary
|
||||||
|
single: binary
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Specifies the command line of the external program to execute.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: binary
|
||||||
|
:Scope: action
|
||||||
|
:Type: string
|
||||||
|
:Default: none
|
||||||
|
:Required?: yes
|
||||||
|
:Introduced: at least 5.x, possibly earlier
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Full path and command line parameters of the external program to execute.
|
||||||
|
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.
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-binary:
|
||||||
|
.. _omprog.parameter.action.binary-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog" binary="/usr/libexec/rsyslog/log.sh")
|
||||||
|
|
||||||
|
Legacy names (for reference)
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
Historic names/directives for compatibility. Do not use in new configs.
|
||||||
|
|
||||||
|
.. _omprog.parameter.legacy.actionomprogbinary:
|
||||||
|
|
||||||
|
- $ActionOMProgBinary — maps to binary (status: legacy)
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; $ActionOMProgBinary
|
||||||
|
single: $ActionOMProgBinary
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
47
doc/source/reference/parameters/omprog-closetimeout.rst
Normal file
47
doc/source/reference/parameters/omprog-closetimeout.rst
Normal file
@ -0,0 +1,47 @@
|
|||||||
|
.. _param-omprog-closetimeout:
|
||||||
|
.. _omprog.parameter.action.closetimeout:
|
||||||
|
|
||||||
|
closeTimeout
|
||||||
|
============
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; closeTimeout
|
||||||
|
single: closeTimeout
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Waits the specified milliseconds for the program to exit after stdin closes.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: closeTimeout
|
||||||
|
:Scope: action
|
||||||
|
:Type: integer
|
||||||
|
:Default: action=5000
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: 8.35.0
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Specifies how long rsyslog must wait for the external program to terminate
|
||||||
|
(when either the worker thread has been unscheduled, a restart of the program
|
||||||
|
is being forced, or rsyslog is about to shutdown) after closing the pipe,
|
||||||
|
that is, after sending EOF to the stdin of the child process. The value must
|
||||||
|
be expressed in milliseconds and must be greater than or equal to zero.
|
||||||
|
|
||||||
|
See the :ref:`param-omprog-killunresponsive` parameter for more details.
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-closetimeout:
|
||||||
|
.. _omprog.parameter.action.closetimeout-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog" closeTimeout="10000")
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
@ -0,0 +1,45 @@
|
|||||||
|
.. _param-omprog-committransactionmark:
|
||||||
|
.. _omprog.parameter.action.committransactionmark:
|
||||||
|
|
||||||
|
commitTransactionMark
|
||||||
|
======================
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; commitTransactionMark
|
||||||
|
single: commitTransactionMark
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Defines the marker sent to denote the end of a transaction.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: commitTransactionMark
|
||||||
|
:Scope: action
|
||||||
|
:Type: string
|
||||||
|
:Default: action="COMMIT TRANSACTION"
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: 8.31.0
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Allows specifying the mark message that rsyslog will send to the external
|
||||||
|
program to indicate the end of a transaction (batch). This parameter is
|
||||||
|
ignored if :ref:`param-omprog-usetransactions` is disabled.
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-committransactionmark:
|
||||||
|
.. _omprog.parameter.action.committransactionmark-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog"
|
||||||
|
useTransactions="on"
|
||||||
|
commitTransactionMark="COMMIT TRANSACTION")
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
65
doc/source/reference/parameters/omprog-confirmmessages.rst
Normal file
65
doc/source/reference/parameters/omprog-confirmmessages.rst
Normal file
@ -0,0 +1,65 @@
|
|||||||
|
.. _param-omprog-confirmmessages:
|
||||||
|
.. _omprog.parameter.action.confirmmessages:
|
||||||
|
|
||||||
|
confirmMessages
|
||||||
|
===============
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; confirmMessages
|
||||||
|
single: confirmMessages
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Waits for the program to acknowledge each message via stdout.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: confirmMessages
|
||||||
|
:Scope: action
|
||||||
|
:Type: boolean
|
||||||
|
:Default: action=off
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: 8.31.0
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Specifies whether the external program provides feedback to rsyslog via stdout.
|
||||||
|
When this switch is set to "on", rsyslog will wait for the program to confirm
|
||||||
|
each received message. This feature facilitates error handling: instead of
|
||||||
|
having to implement a retry logic, the external program can rely on the rsyslog
|
||||||
|
queueing capabilities.
|
||||||
|
|
||||||
|
To confirm a message, the program must write a line with the word ``OK`` to its
|
||||||
|
standard output. If it writes a line containing anything else, rsyslog considers
|
||||||
|
that the message could not be processed, keeps it in the action queue, and
|
||||||
|
re-sends it to the program later (after the period specified by the
|
||||||
|
:doc:`action.resumeInterval <../../configuration/actions>` parameter).
|
||||||
|
|
||||||
|
In addition, when a new instance of the program is started, rsyslog will also
|
||||||
|
wait for the program to confirm it is ready to start consuming logs. This
|
||||||
|
prevents rsyslog from starting to send logs to a program that could not
|
||||||
|
complete its initialization properly.
|
||||||
|
|
||||||
|
.. seealso::
|
||||||
|
|
||||||
|
`Interface between rsyslog and external output plugins
|
||||||
|
<https://github.com/rsyslog/rsyslog/blob/master/plugins/external/INTERFACE.md>`_
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-confirmmessages:
|
||||||
|
.. _omprog.parameter.action.confirmmessages-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog" confirmMessages="on")
|
||||||
|
|
||||||
|
Notes
|
||||||
|
-----
|
||||||
|
- Legacy documentation referred to the type as ``binary``; this maps to ``boolean``.
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
53
doc/source/reference/parameters/omprog-confirmtimeout.rst
Normal file
53
doc/source/reference/parameters/omprog-confirmtimeout.rst
Normal file
@ -0,0 +1,53 @@
|
|||||||
|
.. _param-omprog-confirmtimeout:
|
||||||
|
.. _omprog.parameter.action.confirmtimeout:
|
||||||
|
|
||||||
|
confirmTimeout
|
||||||
|
==============
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; confirmTimeout
|
||||||
|
single: confirmTimeout
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Sets the maximum time in milliseconds to wait for message confirmations.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: confirmTimeout
|
||||||
|
:Scope: action
|
||||||
|
:Type: integer
|
||||||
|
:Default: action=10000
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: 8.38.0
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Specifies how long rsyslog must wait for the external program to confirm
|
||||||
|
each message when :ref:`param-omprog-confirmmessages` is set to "on".
|
||||||
|
If the program does not send a response within this timeout, it will be restarted
|
||||||
|
(see :ref:`param-omprog-signalonclose`, :ref:`param-omprog-closetimeout` and
|
||||||
|
:ref:`param-omprog-killunresponsive` for details on the cleanup sequence).
|
||||||
|
The value must be expressed in milliseconds and must be greater than zero.
|
||||||
|
|
||||||
|
.. seealso::
|
||||||
|
|
||||||
|
`Interface between rsyslog and external output plugins
|
||||||
|
<https://github.com/rsyslog/rsyslog/blob/master/plugins/external/INTERFACE.md>`_
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-confirmtimeout:
|
||||||
|
.. _omprog.parameter.action.confirmtimeout-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog"
|
||||||
|
confirmMessages="on"
|
||||||
|
confirmTimeout="20000")
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
47
doc/source/reference/parameters/omprog-filecreatemode.rst
Normal file
47
doc/source/reference/parameters/omprog-filecreatemode.rst
Normal file
@ -0,0 +1,47 @@
|
|||||||
|
.. _param-omprog-filecreatemode:
|
||||||
|
.. _omprog.parameter.action.filecreatemode:
|
||||||
|
|
||||||
|
fileCreateMode
|
||||||
|
==============
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; fileCreateMode
|
||||||
|
single: fileCreateMode
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Sets permissions for the output file when it is created.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: fileCreateMode
|
||||||
|
:Scope: action
|
||||||
|
:Type: string
|
||||||
|
:Default: action=0600
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: v8.38.0
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Permissions the :ref:`param-omprog-output` file will be created with, in case the file does not
|
||||||
|
exist. The value must be a 4-digit octal number, with the initial digit being
|
||||||
|
zero. Please note that the actual permission depends on the rsyslogd process
|
||||||
|
umask. If in doubt, use ``$umask 0000`` right at the beginning of the
|
||||||
|
configuration file to remove any restrictions.
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-filecreatemode:
|
||||||
|
.. _omprog.parameter.action.filecreatemode-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog"
|
||||||
|
output="/var/log/prog.log"
|
||||||
|
fileCreateMode="0640")
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
@ -0,0 +1,61 @@
|
|||||||
|
.. _param-omprog-forcesingleinstance:
|
||||||
|
.. _omprog.parameter.action.forcesingleinstance:
|
||||||
|
|
||||||
|
forceSingleInstance
|
||||||
|
===================
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; forceSingleInstance
|
||||||
|
single: forceSingleInstance
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Runs only one instance of the program regardless of worker threads.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: forceSingleInstance
|
||||||
|
:Scope: action
|
||||||
|
:Type: boolean
|
||||||
|
:Default: action=off
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: v8.1.6
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
By default, the omprog action will start an instance (process) of the
|
||||||
|
external program per worker thread (the maximum number of worker threads
|
||||||
|
can be specified with the :doc:`queue.workerThreads <../../rainerscript/queue_parameters>`
|
||||||
|
parameter). Moreover, if the action is associated to a
|
||||||
|
:doc:`disk-assisted queue <../../concepts/queues>`, an additional instance
|
||||||
|
will be started when the queue is persisted, to process the items stored
|
||||||
|
on disk.
|
||||||
|
|
||||||
|
If you want to force a single instance of the program to be executed,
|
||||||
|
regardless of the number of worker threads or the queue type, set this
|
||||||
|
flag to "on". This is useful when the external program uses or accesses
|
||||||
|
some kind of shared resource that does not allow concurrent access from
|
||||||
|
multiple processes.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Before version v8.38.0, this parameter had no effect.
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-forcesingleinstance:
|
||||||
|
.. _omprog.parameter.action.forcesingleinstance-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog" forceSingleInstance="on")
|
||||||
|
|
||||||
|
Notes
|
||||||
|
-----
|
||||||
|
- Legacy documentation referred to the type as ``binary``; this maps to ``boolean``.
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
44
doc/source/reference/parameters/omprog-hup-signal.rst
Normal file
44
doc/source/reference/parameters/omprog-hup-signal.rst
Normal file
@ -0,0 +1,44 @@
|
|||||||
|
.. _param-omprog-hup-signal:
|
||||||
|
.. _omprog.parameter.action.hup-signal:
|
||||||
|
|
||||||
|
hup.signal
|
||||||
|
==========
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; hup.signal
|
||||||
|
single: hup.signal
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Forwards a chosen signal to the program when rsyslog receives HUP.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: hup.signal
|
||||||
|
:Scope: action
|
||||||
|
:Type: word
|
||||||
|
:Default: action=none
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: 8.9.0
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Specifies which signal, if any, is to be forwarded to the external program
|
||||||
|
when rsyslog receives a HUP signal. Currently, HUP, USR1, USR2, INT, and
|
||||||
|
TERM are supported. If unset, no signal is sent on HUP. This is the default
|
||||||
|
and what pre 8.9.0 versions did.
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-hup-signal:
|
||||||
|
.. _omprog.parameter.action.hup-signal-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog" hup.signal="HUP")
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
64
doc/source/reference/parameters/omprog-killunresponsive.rst
Normal file
64
doc/source/reference/parameters/omprog-killunresponsive.rst
Normal file
@ -0,0 +1,64 @@
|
|||||||
|
.. _param-omprog-killunresponsive:
|
||||||
|
.. _omprog.parameter.action.killunresponsive:
|
||||||
|
|
||||||
|
killUnresponsive
|
||||||
|
================
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; killUnresponsive
|
||||||
|
single: killUnresponsive
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Kills the program if it remains after the close timeout expires.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: killUnresponsive
|
||||||
|
:Scope: action
|
||||||
|
:Type: boolean
|
||||||
|
:Default: action=the value of 'signalOnClose'
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: 8.35.0
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Specifies whether a KILL signal must be sent to the external program in case
|
||||||
|
it does not terminate within the timeout indicated by :ref:`param-omprog-closetimeout`
|
||||||
|
(when either the worker thread has been unscheduled, a restart of the program
|
||||||
|
is being forced, or rsyslog is about to shutdown).
|
||||||
|
|
||||||
|
If :ref:`param-omprog-signalonclose` is set to "on", the default value of ``killUnresponsive``
|
||||||
|
is also "on". In this case, the cleanup sequence of the child process is as
|
||||||
|
follows: (1) a TERM signal is sent to the child, (2) the pipe with the child
|
||||||
|
process is closed (the child will receive EOF on stdin), (3) rsyslog waits
|
||||||
|
for the child process to terminate during :ref:`param-omprog-closetimeout`,
|
||||||
|
(4) if the child has not terminated within the timeout, a KILL signal is sent to it.
|
||||||
|
|
||||||
|
If :ref:`param-omprog-signalonclose` is set to "off", the default value of ``killUnresponsive``
|
||||||
|
is also "off". In this case, the child cleanup sequence is as follows: (1) the
|
||||||
|
pipe with the child process is closed (the child will receive EOF on stdin),
|
||||||
|
(2) rsyslog waits for the child process to terminate during :ref:`param-omprog-closetimeout`,
|
||||||
|
(3) if the child has not terminated within the timeout, rsyslog ignores it.
|
||||||
|
|
||||||
|
This parameter can be set to a different value than :ref:`param-omprog-signalonclose`, obtaining
|
||||||
|
the corresponding variations of cleanup sequences described above.
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-killunresponsive:
|
||||||
|
.. _omprog.parameter.action.killunresponsive-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog" killUnresponsive="on")
|
||||||
|
|
||||||
|
Notes
|
||||||
|
-----
|
||||||
|
- Legacy documentation referred to the type as ``binary``; this maps to ``boolean``.
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
71
doc/source/reference/parameters/omprog-output.rst
Normal file
71
doc/source/reference/parameters/omprog-output.rst
Normal file
@ -0,0 +1,71 @@
|
|||||||
|
.. _param-omprog-output:
|
||||||
|
.. _omprog.parameter.action.output:
|
||||||
|
|
||||||
|
output
|
||||||
|
======
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; output
|
||||||
|
single: output
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Appends the program's output streams to the specified file.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: output
|
||||||
|
:Scope: action
|
||||||
|
:Type: string
|
||||||
|
:Default: action=none
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: v8.1.6
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Full path of a file where the output of the external program will be saved.
|
||||||
|
If the file already exists, the output is appended to it. If the file does
|
||||||
|
not exist, it is created with the permissions specified by :ref:`param-omprog-filecreatemode`.
|
||||||
|
|
||||||
|
If :ref:`param-omprog-confirmmessages` is set to "off" (the default), both the stdout and
|
||||||
|
stderr of the child process are written to the specified file.
|
||||||
|
|
||||||
|
If :ref:`param-omprog-confirmmessages` is set to "on", only the stderr of the child is
|
||||||
|
written to the specified file (since stdout is used for confirming the
|
||||||
|
messages).
|
||||||
|
|
||||||
|
Rsyslog will reopen the file whenever it receives a HUP signal. This allows
|
||||||
|
the file to be externally rotated (using a tool like *logrotate*): after
|
||||||
|
each rotation of the file, make sure a HUP signal is sent to rsyslogd.
|
||||||
|
|
||||||
|
If the omprog action is configured to use multiple worker threads
|
||||||
|
(:doc:`queue.workerThreads <../../rainerscript/queue_parameters>` is
|
||||||
|
set to a value greater than 1), the lines written by the various program
|
||||||
|
instances will not appear intermingled in the output file, as long as the
|
||||||
|
lines do not exceed a certain length and the program writes them to
|
||||||
|
stdout/stderr in line-buffered mode. For details, refer to `Interface between
|
||||||
|
rsyslog and external output plugins
|
||||||
|
<https://github.com/rsyslog/rsyslog/blob/master/plugins/external/INTERFACE.md>`_.
|
||||||
|
|
||||||
|
If this parameter is not specified, the output of the program will be
|
||||||
|
redirected to ``/dev/null``.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Before version v8.38.0, this parameter was intended for debugging purposes
|
||||||
|
only. Since v8.38.0, the parameter can be used for production.
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-output:
|
||||||
|
.. _omprog.parameter.action.output-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog" output="/var/log/prog.log")
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
56
doc/source/reference/parameters/omprog-reportfailures.rst
Normal file
56
doc/source/reference/parameters/omprog-reportfailures.rst
Normal file
@ -0,0 +1,56 @@
|
|||||||
|
.. _param-omprog-reportfailures:
|
||||||
|
.. _omprog.parameter.action.reportfailures:
|
||||||
|
|
||||||
|
reportFailures
|
||||||
|
==============
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; reportFailures
|
||||||
|
single: reportFailures
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Logs a warning when the program signals an error while confirming messages.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: reportFailures
|
||||||
|
:Scope: action
|
||||||
|
:Type: boolean
|
||||||
|
:Default: action=off
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: 8.38.0
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Specifies whether rsyslog must internally log a warning message whenever the
|
||||||
|
program returns an error when confirming a message. The logged message will
|
||||||
|
include the error line returned by the program. This parameter is ignored when
|
||||||
|
:ref:`param-omprog-confirmmessages` is set to "off".
|
||||||
|
|
||||||
|
Enabling this flag can be useful to log the problems detected by the program.
|
||||||
|
However, the information that can be logged is limited to a short error line,
|
||||||
|
and the logs will be tagged as originated by the 'syslog' facility (like the
|
||||||
|
rest of rsyslog logs). To avoid these shortcomings, consider the use of the
|
||||||
|
:ref:`param-omprog-output` parameter to capture the stderr of the program.
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-reportfailures:
|
||||||
|
.. _omprog.parameter.action.reportfailures-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog"
|
||||||
|
confirmMessages="on"
|
||||||
|
reportFailures="on")
|
||||||
|
|
||||||
|
Notes
|
||||||
|
-----
|
||||||
|
- Legacy documentation referred to the type as ``binary``; this maps to ``boolean``.
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
57
doc/source/reference/parameters/omprog-signalonclose.rst
Normal file
57
doc/source/reference/parameters/omprog-signalonclose.rst
Normal file
@ -0,0 +1,57 @@
|
|||||||
|
.. _param-omprog-signalonclose:
|
||||||
|
.. _omprog.parameter.action.signalonclose:
|
||||||
|
|
||||||
|
signalOnClose
|
||||||
|
=============
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; signalOnClose
|
||||||
|
single: signalOnClose
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Sends a TERM signal to the program before closing its stdin.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: signalOnClose
|
||||||
|
:Scope: action
|
||||||
|
:Type: boolean
|
||||||
|
:Default: action=off
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: 8.23.0
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Specifies whether a TERM signal must be sent to the external program before
|
||||||
|
closing it (when either the worker thread has been unscheduled, a restart
|
||||||
|
of the program is being forced, or rsyslog is about to shutdown).
|
||||||
|
|
||||||
|
If this switch is set to "on", rsyslog will send a TERM signal to the child
|
||||||
|
process before closing the pipe. That is, the process will first receive a
|
||||||
|
TERM signal, and then an EOF on stdin.
|
||||||
|
|
||||||
|
No signal is issued if this switch is set to "off" (default). The child
|
||||||
|
process can still detect it must terminate because reading from stdin will
|
||||||
|
return EOF.
|
||||||
|
|
||||||
|
See the :ref:`param-omprog-killunresponsive` parameter for more details.
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-signalonclose:
|
||||||
|
.. _omprog.parameter.action.signalonclose-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog" signalOnClose="on")
|
||||||
|
|
||||||
|
Notes
|
||||||
|
-----
|
||||||
|
- Legacy documentation referred to the type as ``binary``; this maps to ``boolean``.
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
42
doc/source/reference/parameters/omprog-template.rst
Normal file
42
doc/source/reference/parameters/omprog-template.rst
Normal file
@ -0,0 +1,42 @@
|
|||||||
|
.. _param-omprog-template:
|
||||||
|
.. _omprog.parameter.action.template:
|
||||||
|
|
||||||
|
template
|
||||||
|
========
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; template
|
||||||
|
single: template
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Sets the template for formatting messages sent to the program.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: template
|
||||||
|
:Scope: action
|
||||||
|
:Type: word
|
||||||
|
:Default: action=RSYSLOG_FileFormat
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: at least 5.x, possibly earlier
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Name of the :doc:`template <../../configuration/templates>` to use to format the log messages
|
||||||
|
passed to the external program.
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-template:
|
||||||
|
.. _omprog.parameter.action.template-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog" template="RSYSLOG_FileFormat")
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
69
doc/source/reference/parameters/omprog-usetransactions.rst
Normal file
69
doc/source/reference/parameters/omprog-usetransactions.rst
Normal file
@ -0,0 +1,69 @@
|
|||||||
|
.. _param-omprog-usetransactions:
|
||||||
|
.. _omprog.parameter.action.usetransactions:
|
||||||
|
|
||||||
|
useTransactions
|
||||||
|
===============
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: omprog; useTransactions
|
||||||
|
single: useTransactions
|
||||||
|
|
||||||
|
.. summary-start
|
||||||
|
|
||||||
|
Enables batch processing with begin and commit transaction markers.
|
||||||
|
|
||||||
|
.. summary-end
|
||||||
|
|
||||||
|
This parameter applies to :doc:`../../configuration/modules/omprog`.
|
||||||
|
|
||||||
|
:Name: useTransactions
|
||||||
|
:Scope: action
|
||||||
|
:Type: boolean
|
||||||
|
:Default: action=off
|
||||||
|
:Required?: no
|
||||||
|
:Introduced: 8.31.0
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
Specifies whether the external program processes the messages in
|
||||||
|
:doc:`batches <../../development/dev_oplugins>` (transactions). When this
|
||||||
|
switch is enabled, the logs sent to the program are grouped in transactions.
|
||||||
|
At the start of a transaction, rsyslog sends a special mark message to the
|
||||||
|
program (see :ref:`param-omprog-begintransactionmark`). At the end of the
|
||||||
|
transaction, rsyslog sends another mark message (see
|
||||||
|
:ref:`param-omprog-committransactionmark`).
|
||||||
|
|
||||||
|
If :ref:`param-omprog-confirmmessages` is also set to "on", the program must
|
||||||
|
confirm both the mark messages and the logs within the transaction. The mark
|
||||||
|
messages must be confirmed by returning ``OK``, and the individual messages by
|
||||||
|
returning ``DEFER_COMMIT`` (instead of ``OK``). Refer to the link below for details.
|
||||||
|
|
||||||
|
.. seealso::
|
||||||
|
|
||||||
|
`Interface between rsyslog and external output plugins
|
||||||
|
<https://github.com/rsyslog/rsyslog/blob/master/plugins/external/INTERFACE.md>`_
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
This feature is currently **experimental**. It could change in future releases
|
||||||
|
without keeping backwards compatibility with existing configurations or the
|
||||||
|
specified interface. There is also a `known issue
|
||||||
|
<https://github.com/rsyslog/rsyslog/issues/2420>`_ with the use of
|
||||||
|
transactions together with ``confirmMessages=on``.
|
||||||
|
|
||||||
|
Action usage
|
||||||
|
------------
|
||||||
|
.. _param-omprog-action-usetransactions:
|
||||||
|
.. _omprog.parameter.action.usetransactions-usage:
|
||||||
|
|
||||||
|
.. code-block:: rsyslog
|
||||||
|
|
||||||
|
action(type="omprog" useTransactions="on")
|
||||||
|
|
||||||
|
Notes
|
||||||
|
-----
|
||||||
|
- Legacy documentation referred to the type as ``binary``; this maps to ``boolean``.
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
See also :doc:`../../configuration/modules/omprog`.
|
||||||
Loading…
x
Reference in New Issue
Block a user