From f7f20c3f5e0be02585741f5f54d198689ccd7866 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 18:27:18 +0200 Subject: Adding upstream version 8.2402.0+dfsg. Signed-off-by: Daniel Baumann --- .../options/rsconf1_abortonuncleanconfig.rst | 40 ++++++ .../rsconf1_debugprintcfsyslinehandlerlist.rst | 13 ++ .../options/rsconf1_debugprintmodulelist.rst | 12 ++ .../options/rsconf1_debugprinttemplatelist.rst | 12 ++ .../global/options/rsconf1_failonchownfailure.rst | 21 +++ .../global/options/rsconf1_generateconfiggraph.rst | 148 +++++++++++++++++++++ .../global/options/rsconf1_includeconfig.rst | 74 +++++++++++ .../global/options/rsconf1_mainmsgqueuesize.rst | 34 +++++ .../global/options/rsconf1_maxopenfiles.rst | 36 +++++ .../global/options/rsconf1_moddir.rst | 20 +++ .../global/options/rsconf1_modload.rst | 30 +++++ .../options/rsconf1_resetconfigvariables.rst | 19 +++ .../configuration/global/options/rsconf1_umask.rst | 25 ++++ .../global/options/rsyslog_confgraph_complex.png | Bin 0 -> 143204 bytes .../global/options/rsyslog_confgraph_std.png | Bin 0 -> 167756 bytes 15 files changed, 484 insertions(+) create mode 100644 source/configuration/global/options/rsconf1_abortonuncleanconfig.rst create mode 100644 source/configuration/global/options/rsconf1_debugprintcfsyslinehandlerlist.rst create mode 100644 source/configuration/global/options/rsconf1_debugprintmodulelist.rst create mode 100644 source/configuration/global/options/rsconf1_debugprinttemplatelist.rst create mode 100644 source/configuration/global/options/rsconf1_failonchownfailure.rst create mode 100644 source/configuration/global/options/rsconf1_generateconfiggraph.rst create mode 100644 source/configuration/global/options/rsconf1_includeconfig.rst create mode 100644 source/configuration/global/options/rsconf1_mainmsgqueuesize.rst create mode 100644 source/configuration/global/options/rsconf1_maxopenfiles.rst create mode 100644 source/configuration/global/options/rsconf1_moddir.rst create mode 100644 source/configuration/global/options/rsconf1_modload.rst create mode 100644 source/configuration/global/options/rsconf1_resetconfigvariables.rst create mode 100644 source/configuration/global/options/rsconf1_umask.rst create mode 100644 source/configuration/global/options/rsyslog_confgraph_complex.png create mode 100644 source/configuration/global/options/rsyslog_confgraph_std.png (limited to 'source/configuration/global/options') 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 `_ + +$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 `_\ ] + 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 `_ 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 `_ 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 `_. +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 `_ 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 `_\ ] + 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 Binary files /dev/null and b/source/configuration/global/options/rsyslog_confgraph_complex.png differ 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 Binary files /dev/null and b/source/configuration/global/options/rsyslog_confgraph_std.png differ -- cgit v1.2.3