mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-16 02:50:40 +01: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::
|
||||
|
||||
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
|
||||
-----------------
|
||||
|
||||
template
|
||||
^^^^^^^^
|
||||
|
||||
.. csv-table::
|
||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
||||
:widths: auto
|
||||
:class: parameter-table
|
||||
|
||||
"word", "RSYSLOG_FileFormat", "no", "none"
|
||||
|
||||
Name of the :doc:`template <../templates>` to use to format the log messages
|
||||
passed to the external program.
|
||||
|
||||
|
||||
binary
|
||||
^^^^^^
|
||||
|
||||
.. csv-table::
|
||||
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
|
||||
:widths: auto
|
||||
:class: parameter-table
|
||||
|
||||
"string", "", "yes", "``$ActionOMProgBinary``"
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. _confirmMessages:
|
||||
|
||||
confirmMessages
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. 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 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 <../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>`_
|
||||
|
||||
|
||||
.. _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.
|
||||
|
||||
.. list-table::
|
||||
:widths: 30 70
|
||||
:header-rows: 1
|
||||
|
||||
* - Parameter
|
||||
- Summary
|
||||
* - :ref:`param-omprog-template`
|
||||
- .. include:: ../../reference/parameters/omprog-template.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-binary`
|
||||
- .. include:: ../../reference/parameters/omprog-binary.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-confirmmessages`
|
||||
- .. include:: ../../reference/parameters/omprog-confirmmessages.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-confirmtimeout`
|
||||
- .. include:: ../../reference/parameters/omprog-confirmtimeout.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-reportfailures`
|
||||
- .. include:: ../../reference/parameters/omprog-reportfailures.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-usetransactions`
|
||||
- .. include:: ../../reference/parameters/omprog-usetransactions.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-begintransactionmark`
|
||||
- .. include:: ../../reference/parameters/omprog-begintransactionmark.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-committransactionmark`
|
||||
- .. include:: ../../reference/parameters/omprog-committransactionmark.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-output`
|
||||
- .. include:: ../../reference/parameters/omprog-output.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-filecreatemode`
|
||||
- .. include:: ../../reference/parameters/omprog-filecreatemode.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-hup-signal`
|
||||
- .. include:: ../../reference/parameters/omprog-hup-signal.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-signalonclose`
|
||||
- .. include:: ../../reference/parameters/omprog-signalonclose.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-closetimeout`
|
||||
- .. include:: ../../reference/parameters/omprog-closetimeout.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-killunresponsive`
|
||||
- .. include:: ../../reference/parameters/omprog-killunresponsive.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omprog-forcesingleinstance`
|
||||
- .. include:: ../../reference/parameters/omprog-forcesingleinstance.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
|
||||
Examples
|
||||
========
|
||||
@ -523,8 +204,3 @@ Note that the ``useTransactions`` flag is not used in this example. The
|
||||
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