Adding upstream version 8.2402.0+dfsg.upstream/8.2402.0+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 153 insertions, 0 deletions

diff --git a/source/rainerscript/include.rst b/source/rainerscript/include.rst
new file mode 100644
index 0000000..f2a01c2
--- /dev/null
+++ b/source/rainerscript/include.rst
@@ -0,0 +1,153 @@
+****************************
+The rsyslog include() object
+****************************
+
+The ``include()`` object is used to include configuration snippets
+stored elsewhere into the configuration.
+
+.. versionadded:: 8.33.0
+
+.. note::
+
+   This configuration option deprecates the older ``$IncludeConfig``
+   |FmtObsoleteName| format directive.
+
+How it Works
+============
+
+The rsyslog include object is modelled after the usual "include" directive
+in programming and script languages (e.g. \#include in C).
+
+If you are not familiar with this, compare it to copy and paste: whenever
+rsyslog finds an include object, in copies the text from that include file
+at the exact position where the include is specified and removes the include
+text.
+
+Now remember that rsyslog's configuration statements are depending on the
+position inside the configuration. It is important if a statement occurs
+before or after another one. This is similar how other configuration files
+work and also the same concept that almost all programming and script
+languages have.
+
+If you use includes in rsyslog, you must think about the position at which
+the include text is inserted. This is especially important if you use
+statements like `stop`. If given at the wrong spot, they will not work as
+intended.
+
+If in doubt, or if you have issues, it probably is best NOT to use includes.
+This makes it far more obvious to understand what happens. Once solved, you
+may then change back to includes again.
+
+
+Parameters
+==========
+
+.. note::
+
+   Parameter names are case-insensitive.
+
+.. warning::
+
+   Only one of the ``file`` or ``text`` parameters may be specified for each
+   ``include()`` object.
+
+
+file
+----
+
+Name of file to be included. May include wildcards, in which case all
+matching files are included (in order of file name sort order).
+
+
+text
+----
+
+Text to be included. This is most useful when using backtick string
+constants.
+
+
+mode
+----
+
+Affects how missing files are to be handled:
+
+- ``abort-if-missing``, with rsyslog aborting when the file is not present
+- ``required`` *(default)*, with rsyslog emitting an error message but otherwise
+  continuing when the file is not present
+- ``optional``, which means non-present files will be skipped without notice
+
+Examples
+========
+
+Include a required file
+-----------------------
+
+.. code-block:: none
+
+   include(file="/path/to/include.conf")
+
+.. note::
+
+   Unless otherwise specified, files referenced by an ``include()`` object
+   must be present, otherwise an error will be generated.
+
+
+Include an optional file
+------------------------
+
+The referenced file will be used if found, otherwise no errors or warnings
+will be generated regarding its absence.
+
+.. code-block:: none
+   :emphasize-lines: 3
+
+   include(
+      file="/path/to/include.conf"
+      mode="optional"
+   )
+
+
+Include multiple files
+----------------------
+
+.. code-block:: none
+
+   include(file="/etc/rsyslog.d/*.conf")
+
+.. note::
+
+   Unless otherwise specified, files referenced by an ``include()`` object
+   must be present, otherwise an error will be generated.
+
+
+Include an environment variable as configuration
+------------------------------------------------
+
+.. code-block:: none
+
+   include(text=`echo $ENV_VAR`)
+
+
+Include a file specified via an environment variable
+----------------------------------------------------
+
+.. code-block:: none
+
+   include(file=`echo $ENV_VAR`)
+
+.. note::
+
+   Unless otherwise specified, files referenced by an ``include()`` object
+   must be present, otherwise an error will be generated.
+
+
+Include an optional file specified via an environment variable
+--------------------------------------------------------------
+
+.. code-block:: none
+   :emphasize-lines: 3
+
+   include(
+      file=`echo $ENV_VAR`
+      mode="optional"
+   )