imklog: Kernel Log Input Module
===============================

Reads messages from the kernel log and submits them to the syslog
engine.

**Author:**\ Rainer Gerhards <rgerhards@adiscon.com>

Configuration Directives
------------------------

.. function:: $KLogInternalMsgFacility <facility>

   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.

.. function:: $KLogPermitNonKernelFacility off

   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.

.. function:: $DebugPrintKernelSymbols on/off

   Linux only, ignored on other platforms (but may be specified).
   Defaults to off.

.. function:: $klogLocalIPIF [interface name]

   If provided, the IP of the specified interface (e.g. "eth0") shall be
   used as fromhost-ip for imklog-originating messages. If this
   directive is not given OR the interface cannot be found (or has no IP
   address), the default of "127.0.0.1" is used.

.. function:: $klogConsoleLogLevel <number>

   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)

.. 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.

.. function:: $klogParseKernelTimestamp on/off

   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.

.. function:: $klogKeepKernelTimestamp on/off

   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.

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
-------

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.

::

  $ModLoad imklog


