diff options
Diffstat (limited to 'source/configuration/modules/imklog.rst')
| -rw-r--r-- | source/configuration/modules/imklog.rst | 230 |
1 files changed, 230 insertions, 0 deletions
diff --git a/source/configuration/modules/imklog.rst b/source/configuration/modules/imklog.rst new file mode 100644 index 0000000..2de34ed --- /dev/null +++ b/source/configuration/modules/imklog.rst @@ -0,0 +1,230 @@ +******************************* +imklog: Kernel Log Input Module +******************************* + +=========================== =========================================================================== +**Module Name:** **imklog** +**Author:** `Rainer Gerhards <https://rainer.gerhards.net/>`_ <rgerhards@adiscon.com> +=========================== =========================================================================== + + +Purpose +======= + +Reads messages from the kernel log and submits them to the syslog +engine. + + +Configuration Parameters +======================== + +.. note:: + + Parameter names are case-insensitive. + + +Module Parameters +----------------- + +InternalMsgFacility +^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "facility", "(see description)", "no", "``$KLogInternalMsgFacility``" + +The facility which messages internally generated by imklog will +have. imklog generates some messages of itself (e.g. on problems, +startup and shutdown) and these do not stem from the kernel. +Historically, under Linux, these too have "kern" facility. Thus, on +Linux platforms the default is "kern" while on others it is +"syslogd". You usually do not need to specify this configuration +directive - it is included primarily for few limited cases where it +is needed for good reason. Bottom line: if you don't have a good idea +why you should use this setting, do not touch it. + + +PermitNonKernelFacility +^^^^^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "``$KLogPermitNonKernelFacility``" + +At least under BSD the kernel log may contain entries with +non-kernel facilities. This setting controls how those are handled. +The default is "off", in which case these messages are ignored. +Switch it to on to submit non-kernel messages to rsyslog processing. + + +ConsoleLogLevel +^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "integer", "-1", "no", "``$klogConsoleLogLevel``" + +Sets the console log level. If specified, only messages with up to +the specified level are printed to the console. The default is -1, +which means that the current settings are not modified. To get this +behavior, do not specify $klogConsoleLogLevel in the configuration +file. Note that this is a global parameter. Each time it is changed, +the previous definition is re-set. The one activate will be that one +that is active when imklog actually starts processing. In short +words: do not specify this directive more than once! + +**Linux only**, ignored on other platforms (but may be specified) + + +ParseKernelTimestamp +^^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "``$klogParseKernelTimestamp``" + +If enabled and the kernel creates a timestamp for its log messages, +this timestamp will be parsed and converted into regular message time +instead to use the receive time of the kernel message (as in 5.8.x +and before). Default is 'off' to prevent parsing the kernel timestamp, +because the clock used by the kernel to create the timestamps is not +supposed to be as accurate as the monotonic clock required to convert +it. Depending on the hardware and kernel, it can result in message +time differences between kernel and system messages which occurred at +same time. + + +KeepKernelTimestamp +^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "``$klogKeepKernelTimestamp``" + +If enabled, this option causes to keep the [timestamp] provided by +the kernel at the begin of in each message rather than to remove it, +when it could be parsed and converted into local time for use as +regular message time. Only used, when $klogParseKernelTimestamp is +on. + + +LogPath +^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "(see description)", "no", "``$klogpath``" + +Defines the path to the log file that is used. +If this parameter is not set a default will be used. +On Linux "/proc/kmsg" and else "/dev/klog". + + +RatelimitInterval +^^^^^^^^^^^^^^^^^ +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "integer", "0", "no", "none" + +.. versionadded:: 8.35.0 + +The rate-limiting interval in seconds. Value 0 turns off rate limiting. +Set it to a number of seconds (5 recommended) to activate rate-limiting. + + +RatelimitBurst +^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "integer", "10000", "no", "none" + +.. versionadded:: 8.35.0 + +Specifies the rate-limiting burst in number of messages. Set it high to +preserve all bootup messages. + + +Caveats/Known Bugs +================== + +This is obviously platform specific and requires platform drivers. +Currently, imklog functionality is available on Linux and BSD. + +This module is **not supported on Solaris** and not needed there. For +Solaris kernel input, use :doc:`imsolaris <imsolaris>`. + + +Example 1 +========= + +The following sample pulls messages from the kernel log. All parameters +are left by default, which is usually a good idea. Please note that +loading the plugin is sufficient to activate it. No directive is needed +to start pulling kernel messages. + +.. code-block:: none + + module(load="imklog") + + +Example 2 +========= + +The following sample adds a ratelimiter. The burst and interval are +set high to allow for a large volume of messages on boot. + +.. code-block:: none + + module(load="imklog" RatelimitBurst="5000" RatelimitInterval="5") + + +Unsupported |FmtObsoleteName| directives +======================================== + +.. function:: $DebugPrintKernelSymbols on/off + + Linux only, ignored on other platforms (but may be specified). + Defaults to off. + +.. function:: $klogLocalIPIF + + This directive is no longer supported. Instead, use the global + $localHostIPIF directive instead. + + +.. function:: $klogUseSyscallInterface on/off + + Linux only, ignored on other platforms (but may be specified). + Defaults to off. + +.. function:: $klogSymbolsTwice on/off + + Linux only, ignored on other platforms (but may be specified). + Defaults to off. + + |