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

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

15 files changed, 484 insertions, 0 deletions

diff --git a/source/configuration/global/options/rsconf1_abortonuncleanconfig.rst b/source/configuration/global/options/rsconf1_abortonuncleanconfig.rst
new file mode 100644
index 0000000..f1a7fb3
--- /dev/null
+++ b/source/configuration/global/options/rsconf1_abortonuncleanconfig.rst
@@ -0,0 +1,40 @@
+`rsyslog.conf configuration parameter <rsyslog_conf_global.html>`_
+
+$AbortOnUncleanConfig
+----------------------
+
+**Type:** global configuration parameter
+
+**Parameter Values:** boolean (on/off, yes/no)
+
+**Available since:** 5.3.1+
+
+**Default:** off
+
+**Description:**
+
+This parameter permits to prevent rsyslog from running when the
+configuration file is not clean. "Not Clean" means there are errors or
+some other annoyances that rsyslogd reports on startup. This is a
+user-requested feature to have a strict startup mode. Note that with the
+current code base it is not always possible to differentiate between an
+real error and a warning-like condition. As such, the startup will also
+prevented if warnings are present. I consider this a good thing in being
+"strict", but I admit there also currently is no other way of doing it.
+
+It is recommended to use the new config style. The equivalent of this
+parameter in the new style is ``global(abortOnUncleanConfig="")``.
+
+**Caveats:**
+
+Note that the consequences of a failed rsyslogd startup can be much more
+serious than a startup with only partial configuration. For example, log
+data may be lost or systems that depend on the log server in question
+will not be able to send logs, what in the ultimate result could result
+in a system hang on those systems. Also, the local system may hang when
+the local log socket has become full and is not read. There exist many
+such scenarios. As such, it is strongly recommended not to turn on this
+parameter.
+
+[`rsyslog site <http://www.rsyslog.com/>`_\ ]
+
diff --git a/source/configuration/global/options/rsconf1_debugprintcfsyslinehandlerlist.rst b/source/configuration/global/options/rsconf1_debugprintcfsyslinehandlerlist.rst
new file mode 100644
index 0000000..70ceb4c
--- /dev/null
+++ b/source/configuration/global/options/rsconf1_debugprintcfsyslinehandlerlist.rst
@@ -0,0 +1,13 @@
+$DebugPrintCFSyslineHandlerList
+-------------------------------
+
+**Type:** global configuration parameter
+
+**Default:** on
+
+**Description:**
+
+Specifies whether or not the configuration file sysline handler list
+should be written to the debug log. Possible values: on/off. Default is
+on. Does not affect operation if debugging is disabled.
+
diff --git a/source/configuration/global/options/rsconf1_debugprintmodulelist.rst b/source/configuration/global/options/rsconf1_debugprintmodulelist.rst
new file mode 100644
index 0000000..8ddfa79
--- /dev/null
+++ b/source/configuration/global/options/rsconf1_debugprintmodulelist.rst
@@ -0,0 +1,12 @@
+$DebugPrintModuleList
+---------------------
+
+**Type:** global configuration parameter
+
+**Default:** on
+
+**Description:**
+
+Specifies whether or not the module list should be written to the debug
+log. Possible values: on/off. Default is on. Does not affect operation
+if debugging is disabled.
diff --git a/source/configuration/global/options/rsconf1_debugprinttemplatelist.rst b/source/configuration/global/options/rsconf1_debugprinttemplatelist.rst
new file mode 100644
index 0000000..d67a05e
--- /dev/null
+++ b/source/configuration/global/options/rsconf1_debugprinttemplatelist.rst
@@ -0,0 +1,12 @@
+$DebugPrintTemplateList
+-----------------------
+
+**Type:** global configuration parameter
+
+**Default:** on
+
+**Description:**
+
+Specifies whether or not the template list should be written to the
+debug log. Possible values: on/off. Default is on. Does not affect
+operation if debugging is disabled..
diff --git a/source/configuration/global/options/rsconf1_failonchownfailure.rst b/source/configuration/global/options/rsconf1_failonchownfailure.rst
new file mode 100644
index 0000000..01d6c5a
--- /dev/null
+++ b/source/configuration/global/options/rsconf1_failonchownfailure.rst
@@ -0,0 +1,21 @@
+$FailOnChownFailure
+-------------------
+
+**Type:** global configuration parameter
+
+**Default:** on
+
+**Description:**
+
+This option modifies behaviour of dynaFile creation. If different owners
+or groups are specified for new files or directories and rsyslogd fails
+to set these new owners or groups, it will log an error and NOT write to
+the file in question if that option is set to "on". If it is set to
+"off", the error will be ignored and processing continues. Keep in mind,
+that the files in this case may be (in)accessible by people who should
+not have permission. The default is "on".
+
+**Sample:**
+
+``$FailOnChownFailure off``
+
diff --git a/source/configuration/global/options/rsconf1_generateconfiggraph.rst b/source/configuration/global/options/rsconf1_generateconfiggraph.rst
new file mode 100644
index 0000000..4c70832
--- /dev/null
+++ b/source/configuration/global/options/rsconf1_generateconfiggraph.rst
@@ -0,0 +1,148 @@
+$GenerateConfigGraph
+--------------------
+
+**Type:** global configuration parameter
+
+**Default:**
+
+**Available Since:** 4.3.1 **CURRENTLY NOT AVAILABLE**
+
+**Description:**
+
+**This parameter is currently not supported. We had to disable it when
+we improved the rule engine. It is considerable effort to re-enable it.
+On the other hand, we are about to add a new config system, which will
+make yet another config graph method necessary. As such we have decided
+to currently disable this functionality and re-introduce it when the new
+config system has been instantiated.**
+
+This parameter permits to create (hopefully) good-looking visualizations
+of rsyslogd's configuration. It does not affect rsyslog operation. If
+the parameter is specified multiple times, all but the last are ignored.
+If it is specified, a graph is created. This happens both during a
+regular startup as well a config check run. It is recommended to include
+this parameter only for documentation purposes and remove it from a
+production configuration.
+
+The graph is not drawn by rsyslog itself. Instead, it uses the great
+open source tool `Graphviz <http://www.graphviz.org>`_ to do the actual
+drawing. This has at least two advantages:
+
+-  the graph drawing support code in rsyslog is extremely slim and
+   without overhead
+-  the user may change or further annotate the generated file, thus
+   potentially improving his documentation
+
+The drawback, of course, is that you need to run Graphviz once you have
+generated the control file with rsyslog. Fortunately, the process to do
+so is rather easy:
+
+#. add "$GenerateConfigGraph /path/to/file.dot" to rsyslog.conf (from
+   now on, I will call the file just file.dot). Optionally, add
+   "$ActionName" statement **in front of** those actions that you like
+   to use friendly names with. If you do this, keep the names short.
+#. run rsyslog at least once (either in regular or configuration check
+   mode)
+#. remember to remove the $GenerateConfigGraph parameter when you no
+   longer need it (or comment it out)
+#. change your working directory to where you place the dot file
+#. if you would like to edit the rsyslog-generated file, now is the time
+   to do so
+#. do "dot -Tpng file.dot > file.png"
+#. remember that you can use "convert -resize 50% file.png resized.png"
+   if dot's output is too large (likely) or too small. Resizing can be
+   especially useful if you intend to get a rough overview over your
+   configuration.
+
+After completing these steps, you should have a nice graph of your
+configuration. Details are missing, but that is exactly the point. At
+the start of the graph is always (at least in this version, could be
+improved) a node called "inputs" in a triple hexagon shape. This
+represents all inputs active in the system (assuming you have defined
+some, what the current version does not check). Next comes the main
+queue. It is given in a hexagon shape. That shape indicates that a queue
+is present and used to de-couple the inbound from the outbound part of
+the graph. In technical terms, here is a threading boundary. Action with
+"real" queues (other than in direct mode) also utilize this shape. For
+actions, notice that a "hexagon action" creates a deep copy of the
+message. As such, a "discard hexagon action" actually does nothing,
+because it duplicates the message and then discards **the duplicate**.
+At the end of the diagram, you always see a "discard" action. This
+indicates that rsyslog discards messages which have been run through all
+available rules.
+
+Edges are labeled with information about when they are taken. For
+filters, the type of filter, but not any specifics, are given. It is
+also indicated if no filter is applied in the configuration file (by
+using a "\*.\*" selector). Edges without labels are unconditionally
+taken. The actions themselves are labeled with the name of the output
+module that handles them. If provided, the name given via "ActionName"
+is used instead. No further details are provided.
+
+If there is anything in red, this should draw your attention. In this
+case, rsyslogd has detected something that does not look quite right. A
+typical example is a discard action which is followed by some other
+actions in an action unit. Even though something may be red, it can be
+valid - rsyslogd's graph generator does not yet check each and every
+specialty, so the configuration may just cover a very uncommon case.
+
+Now let's look at some examples. The graph below was generated on a
+fairly standard Fedora rsyslog.conf file. It had only the usually
+commented-out last forwarding action activated:
+
+.. figure:: rsyslog_confgraph_std.png
+   :align: center
+   :alt: rsyslog configuration graph for a default fedora rsyslog.conf
+
+   rsyslog configuration graph for a default fedora rsyslog.conf
+
+This is the typical structure for a simple rsyslog configuration. There
+are a couple of actions, each guarded by a filter. Messages run from top
+to bottom and control branches whenever a filter evaluates to true. As
+there is no discard action, all messages will run through all filters
+and discarded in the system default discard action right after all
+configured actions.
+
+A more complex example can be seen in the next graph. This is a
+configuration I created for testing the graph-creation features, so it
+contains a little bit of everything. However, real-world configurations
+can look quite complex, too (and I wouldn't say this one is very
+complex):
+
+.. figure:: rsyslog_confgraph_complex.png
+   :align: center
+   :alt:
+
+Here, we have a user-defined discard action. You can immediately see
+this because processing branches after the first "builtin-file" action.
+Those messages where the filter evaluates to true for will never run
+through the left-hand action branch. However, there is also a
+configuration error present: there are two more actions (now shown red)
+after the discard action. As the message is discarded, these will never
+be executed. Note that the discard branch contains no further filters.
+This is because these actions are all part of the same action unit,
+which is guarded only by an entry filter. The same is present a bit
+further down at the node labeled "write\_system\_log\_2". This note has
+one more special feature, that is label was set via "ActionName", thus
+is does not have standard form (the same happened to the node named
+"Forward" right at the top of the diagram. Inside this diagram, the
+"Forward" node is executed asynchronously on its own queue. All others
+are executed synchronously.
+
+Configuration graphs are useful for documenting a setup, but are also a
+great `troubleshooting <troubleshoot.html>`_ resource. It is important
+to remember that **these graphs are generated from rsyslogd's in-memory
+action processing structures**. You can not get closer to understanding
+on how rsyslog interpreted its configuration files. So if the graph does
+not look what you intended to do, there is probably something wrong in
+rsyslog.conf.
+
+If something is not working as expected, but you do not spot the error
+immediately, I recommend to generate a graph and zoom it so that you see
+all of it in one great picture. You may not be able to read anything,
+but the structure should look good to you and so you can zoom into those
+areas that draw your attention.
+
+**Sample:**
+
+``$DirOwner /path/to/graphfile-file.dot``
diff --git a/source/configuration/global/options/rsconf1_includeconfig.rst b/source/configuration/global/options/rsconf1_includeconfig.rst
new file mode 100644
index 0000000..a177324
--- /dev/null
+++ b/source/configuration/global/options/rsconf1_includeconfig.rst
@@ -0,0 +1,74 @@
+$IncludeConfig
+--------------
+
+.. warning::
+
+   This legacy directive has been superseeded by the rsyslog
+   :doc:`include() <../../../rainerscript/include>`
+   configuration object.
+   While it is save to use the legacy statement, we highly
+   recommend to use it's modern counterpart. Among others,
+   the `include()` object provides enhanced functionality.
+
+**Type:** global configuration parameter
+
+**Default:**
+
+**Description:**
+
+This parameter allows to include other files into the main configuration
+file. As soon as an IncludeConfig parameter is found, the contents of
+the new file is processed. IncludeConfigs can be nested. Please note
+that from a logical point of view the files are merged. Thus, if the
+include modifies some parameters (e.g. $DynaFileCacheSize), these new
+parameters are in place for the "calling" configuration file when the
+include is completed. To avoid any side effects, do a
+$ResetConfigVariables after the $IncludeConfig. It may also be a good
+idea to do a $ResetConfigVariables right at the start of the include, so
+that the module knows exactly what it does. Of course, one might
+specifically NOT do this to inherit parameters from the main file. As
+always, use it as it best fits...
+
+Note: if multiple files are included, they are processed in ascending
+sort order of the file name. We use the "glob()" C library function
+for obtaining the sorted list. On most platforms, especially Linux,
+this means the sort order is the same as for bash.
+
+If all regular files in the /etc/rsyslog.d directory are included, then
+files starting with "." are ignored - so you can use them to place
+comments into the dir (e.g. "/etc/rsyslog.d/.mycomment" will be
+ignored). `Michael Biebl had the idea to this
+functionality <http://sourceforge.net/tracker/index.php?func=detail&aid=1764088&group_id=123448&atid=696555>`_.
+Let me quote him:
+
+    Say you can add an option
+    ``$IncludeConfig /etc/rsyslog.d/``
+    (which probably would make a good default)
+    to ``/etc/rsyslog.conf``, which would then merge and include all
+    ``*.conf`` files
+    in ``/etc/rsyslog.d/``.
+    This way, a distribution can modify its packages easily to drop a
+    simple
+    config file into this directory upon installation.
+    As an example, the network-manager package could install a simple
+    config
+    file ``/etc/rsyslog.d/network-manager.conf`` which would contain.
+    ``:programname, contains, "NetworkManager" -/var/log/NetworkManager.log``
+    Upon uninstallation, the file could be easily removed again. This
+    approach would be much cleaner and less error prone, than having to munge
+    around with the ``/etc/rsyslog.conf`` file directly.
+
+**Sample:**
+
+``$IncludeConfig /etc/some-included-file.conf``
+
+Directories can also be included. To do so, the name must end on a
+slash:
+
+``$IncludeConfig /etc/rsyslog.d/``
+
+**And finally, only specific files matching a wildcard my be included
+from a directory:**
+
+``$IncludeConfig /etc/rsyslog.d/*.conf``
+
diff --git a/source/configuration/global/options/rsconf1_mainmsgqueuesize.rst b/source/configuration/global/options/rsconf1_mainmsgqueuesize.rst
new file mode 100644
index 0000000..8b74b59
--- /dev/null
+++ b/source/configuration/global/options/rsconf1_mainmsgqueuesize.rst
@@ -0,0 +1,34 @@
+$MainMsgQueueSize
+-----------------
+
+**Type:** global configuration parameter
+
+**Default:** 50000 (v8.30.0) - may change
+
+**Description:**
+
+This allows to specify the maximum size of the message queue. This
+parameter is only available when rsyslogd has been compiled with
+multithreading support. In this mode, receiver and output modules are
+de-coupled via an in-memory queue. This queue buffers messages when the
+output modules are not capable to process them as fast as they are
+received. Once the queue size is exhausted, messages will be dropped.
+The slower the output (e.g. MySQL), the larger the queue should be.
+Buffer space for the actual queue entries is allocated on an as-needed
+basis. Please keep in mind that a very large queue may exhaust available
+system memory and swap space. Keep this in mind when configuring the max
+size. The actual size of a message depends largely on its content and
+the originator. As a rule of thumb, typically messages should not take
+up more then roughly 1k (this is the memory structure, not what you see
+in a network dump!). For typical linux messages, 512 bytes should be a
+good bet. Please also note that there is a minimal amount of memory
+taken for each queue entry, no matter if it is used or not. This is one
+pointer value, so on 32bit systems, it should typically be 4 bytes and
+on 64bit systems it should typically be 8 bytes. For example, the
+default queue size of 10,000 entries needs roughly 40k fixed overhead on
+a 32 bit system.
+
+**Sample:**
+
+``$MainMsgQueueSize 100000 # 100,000 may be a value to handle burst traffic``
+
diff --git a/source/configuration/global/options/rsconf1_maxopenfiles.rst b/source/configuration/global/options/rsconf1_maxopenfiles.rst
new file mode 100644
index 0000000..89e4021
--- /dev/null
+++ b/source/configuration/global/options/rsconf1_maxopenfiles.rst
@@ -0,0 +1,36 @@
+$MaxOpenFiles
+-------------
+
+**Available Since:** 4.3.0
+
+**Type:** global configuration parameter
+
+**Default:** *operating system default*
+
+**Description:**
+
+Set the maximum number of files that the rsyslog process can have open
+at any given time. Note that this includes open tcp sockets, so this
+setting is the upper limit for the number of open TCP connections as
+well. If you expect a large number of concurrent connections, it is
+suggested that the number is set to the max number connected plus 1000.
+Please note that each dynafile also requires up to 100 open file
+handles.
+
+The setting is similar to running "ulimit -n number-of-files".
+
+Please note that depending on permissions and operating system
+configuration, the setrlimit() request issued by rsyslog may fail, in
+which case the previous limit is kept in effect. Rsyslog will emit a
+warning message in this case.
+
+**Sample:**
+
+``$MaxOpenFiles 2000``
+
+**Bugs:**
+
+For some reason, this settings seems not to work on all platforms. If
+you experience problems, please let us know so that we can (hopefully)
+narrow down the issue.
+
diff --git a/source/configuration/global/options/rsconf1_moddir.rst b/source/configuration/global/options/rsconf1_moddir.rst
new file mode 100644
index 0000000..c1fa503
--- /dev/null
+++ b/source/configuration/global/options/rsconf1_moddir.rst
@@ -0,0 +1,20 @@
+$ModDir
+-------
+
+**Type:** global configuration parameter
+
+**Default:** system default for user libraries, e.g.
+/usr/local/lib/rsyslog/
+
+**Description:**
+
+Provides the default directory in which loadable modules reside. This
+may be used to specify an alternate location that is not based on the
+system default. If the system default is used, there is no need to
+specify this parameter. Please note that it is vitally important to end
+the path name with a slash, else module loads will fail.
+
+**Sample:**
+
+``$ModDir /usr/rsyslog/libs/  # note the trailing slash!``
+
diff --git a/source/configuration/global/options/rsconf1_modload.rst b/source/configuration/global/options/rsconf1_modload.rst
new file mode 100644
index 0000000..e600784
--- /dev/null
+++ b/source/configuration/global/options/rsconf1_modload.rst
@@ -0,0 +1,30 @@
+$ModLoad
+--------
+
+**Type:** global configuration parameter
+
+**Default:**
+
+**Description:**
+
+Dynamically loads a plug-in into rsyslog's address space and activates
+it. The plug-in must obey the rsyslog module API. Currently, only MySQL
+and Postgres output modules are available as a plugins, but users may
+create their own. A plug-in must be loaded BEFORE any configuration file
+lines that reference it.
+
+Modules must be present in the system default destination for rsyslog
+modules. You can also set the directory via the
+`$ModDir <rsconf1_moddir.html>`_ parameter.
+
+If a full path name is specified, the module is loaded from that path.
+The default module directory is ignored in that case.
+
+**Sample:**
+
+.. code-block:: none
+
+  $ModLoad ommysql # load MySQL functionality
+  $ModLoad /rsyslog/modules/ompgsql.so # load the postgres module via absolute path
+
+
diff --git a/source/configuration/global/options/rsconf1_resetconfigvariables.rst b/source/configuration/global/options/rsconf1_resetconfigvariables.rst
new file mode 100644
index 0000000..8d27c65
--- /dev/null
+++ b/source/configuration/global/options/rsconf1_resetconfigvariables.rst
@@ -0,0 +1,19 @@
+$ResetConfigVariables
+---------------------
+
+**Type:** global configuration parameter
+
+**Default:**
+
+**Description:**
+
+Resets all configuration variables to their default value. Any settings
+made will not be applied to configuration lines following the
+$ResetConfigVariables. This is a good method to make sure no
+side-effects exists from previous parameters. This parameter has no
+parameters.
+
+**Sample:**
+
+``$ResetConfigVariables``
+
diff --git a/source/configuration/global/options/rsconf1_umask.rst b/source/configuration/global/options/rsconf1_umask.rst
new file mode 100644
index 0000000..57ead52
--- /dev/null
+++ b/source/configuration/global/options/rsconf1_umask.rst
@@ -0,0 +1,25 @@
+$UMASK
+------
+
+**Type:** global configuration parameter
+
+**Default:**
+
+**Description:**
+
+The $umask parameter allows to specify the rsyslogd processes' umask. If
+not specified, the system-provided default is used. The value given must
+always be a 4-digit octal number, with the initial digit being zero.
+
+If $umask is specified multiple times in the configuration file, results
+may be somewhat unpredictable. It is recommended to specify it only
+once.
+
+**Sample:**
+
+``$umask 0000``
+
+This sample removes all restrictions.
+
+[`rsyslog site <http://www.rsyslog.com/>`_\ ]
+
diff --git a/source/configuration/global/options/rsyslog_confgraph_complex.png b/source/configuration/global/options/rsyslog_confgraph_complex.png
new file mode 100644
index 0000000..21c04c5
--- /dev/null
+++ b/source/configuration/global/options/rsyslog_confgraph_complex.png
diff --git a/source/configuration/global/options/rsyslog_confgraph_std.png b/source/configuration/global/options/rsyslog_confgraph_std.png
new file mode 100644
index 0000000..655a7f8
--- /dev/null
+++ b/source/configuration/global/options/rsyslog_confgraph_std.png