diff options
Diffstat (limited to 'source/configuration/modules/imkmsg.rst')
-rw-r--r-- | source/configuration/modules/imkmsg.rst | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/source/configuration/modules/imkmsg.rst b/source/configuration/modules/imkmsg.rst new file mode 100644 index 0000000..318c9f5 --- /dev/null +++ b/source/configuration/modules/imkmsg.rst @@ -0,0 +1,188 @@ +********************************** +imkmsg: /dev/kmsg Log Input Module +********************************** + +=========================== =========================================================================== +**Module Name:** **imkmsg** +**Author:** `Rainer Gerhards <https://rainer.gerhards.net/>`_ <rgerhards@adiscon.com> + Milan Bartos <mbartos@redhat.com> +=========================== =========================================================================== + + +Purpose +======= + +Reads messages from the /dev/kmsg structured kernel log and submits them +to the syslog engine. + +The printk log buffer contains log records. These records are exported +by /dev/kmsg device as structured data in the following format: +"level,sequnum,timestamp;<message text>\\n" +There could be continuation lines starting with space that contains +key/value pairs. +Log messages are parsed as necessary into rsyslog msg\_t structure. +Continuation lines are parsed as json key/value pairs and added into +rsyslog's message json representation. + + +Configuration Parameters +======================== + +.. note:: + + Parameter names are case-insensitive. + +Module Parameters +----------------- + +Mode +^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "parseKernelTimestamp", "no", "none" + +.. versionadded:: 8.2312.0 + +This parameter configures which timestamps will be used. It is an advanced +setting and most users should probably keep the default mode ("startup"). + +The linux kernel message buffer contains a timestamp, which reflects the time +the message was created. However, this is not the "normal" time one expects, but +in a so-called monotonic time in seconds since kernel start. For a datacenter +system which runs 24 hours by 7 days a week, kernel time and actual +wall clock time is mostly the same. Problems may occur during daylight +savings time switches. + +For desktops and laptops this is not necessarily the case. The reason is, as +it looks, that during low power states (energy save mode, hibernation), kernel +monotonic time **does not advance**. This is also **not** corrected when the +system comes back to normal operations. As such, on systems using low power +states from time to time, kernel time and wallclock time drift apart. We have +been told cases where this is in the magnitude of days. Just think about +desktops which are in hibernate during the night, missing several hours +each day. So this is a real-world problem. + +To work around this, we usually do **not** use the kernel timstamp when +we calculate the message time. Instead, we use wallclock time (obtained +from the respective linux timer) of the instant when imkmsg reads the +message from the kernel log. As message creation and imkmsg reading it +is usually in very close time proximity, this approach works very well. + +**However**, this is not helpful for e.g. early boot messages. These +were potentially generated some seconds to a minute or two before rsyslog +startup. To provide a proper meaning of time for these events, we use +the kernel timstamp instead of wallclock time during rsyslog startup. +This is most probably correct, because it is extremely unlikely (close +to impossible) that the system entered a low-power state before rsyslog +startup. + +**Note well:** When rsyslog is restarted during normal system operations, +existing imkmsg messages are re-read and this is done with the kernel +timestamp. This causes message duplication, but is what imkmsg always +did. It is planned to provide ehance the module to improve this +behaviour. This documentation page here will be updated when changes are +made. + +The *parseKernelTimestamp* parameter provides fine-grain control over +the processing of kernel vs. wallclock time. Adjustments should only +be needed rarely and if there is a dedicated use case for it. So use +this parameter only if you have a good reason to do so. + +Supported modes are: + +* **startup** - This is the **DEFAULT setting**. + + Uses the kernel time stamp during the initial read + loop of /dev/kmsg, but uses system wallclock time once the initial + read is completed. This behavior is described in the text above in + detail. + +* **on** - kernel timestamps are always used and wallclock time never + +* **off** - kernel timestamps are never used, system wallclock time is + always used + + +readMode +^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "full-boot", "no", "none" + +.. versionadded:: 8.2312.0 + +This parameter permits to control when imkmsg reads the full kernel. + +It provides the following options: + +* **full-boot** - (default) read full klog, but only "immediately" after + boot. "Immediately" is hereby meant in seconds of system uptime + given in "expectedBootCompleteSeconds" + +* **full-always** - read full klog on every rsyslog startup. Most probably + causes message duplication + +* **new-only** - never emit existing kernel log message, read only new ones. + +Note that some message loss can happen if rsyslog is stopped in "full-boot" and +"new-only" read mode. The longer rsyslog is inactive, the higher the message +loss probability and potential number of messages lost. For typical restart +scenarios, this should be minimal. On HUP, no message loss occurs as rsyslog +is not actually stopped. + + +expectedBootCompleteSeconds +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "positive integer", "90", "no", "none" + +.. versionadded:: 8.2312.0 + +This parameter works in conjunction with **readMode** and specifies how +many seconds after startup the system should be considered to be +"just booted", which means in **readMode** "full-boot" imkmsg reads and +forwards to rsyslog processing all existing messages. + +In any other **readMode** the **expectedBootCompleteSettings** is +ignored. + +Caveats/Known Bugs: +=================== + +This module cannot be used together with imklog module. When using one of +them, make sure the other one is not enabled. + +This is Linux specific module and requires /dev/kmsg device with +structured kernel logs. + +This module does not support rulesets. All messages are delivered to the +default rulseset. + + + +Examples +======== + +The following sample pulls messages from the /dev/kmsg log device. 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 messages. + +.. code-block:: none + + module(load="imkmsg") + + |