diff options
Diffstat (limited to 'source/configuration/modules/imuxsock.rst')
| -rw-r--r-- | source/configuration/modules/imuxsock.rst | 966 |
1 files changed, 966 insertions, 0 deletions
diff --git a/source/configuration/modules/imuxsock.rst b/source/configuration/modules/imuxsock.rst new file mode 100644 index 0000000..8c05108 --- /dev/null +++ b/source/configuration/modules/imuxsock.rst @@ -0,0 +1,966 @@ +********************************** +imuxsock: Unix Socket Input Module +********************************** + +=========================== =========================================================================== +**Module Name:** **imuxsock** +**Author:** `Rainer Gerhards <http://www.gerhards.net/rainer>`_ <rgerhards@adiscon.com> +=========================== =========================================================================== + + +Purpose +======= + +This module provides the ability to accept syslog messages from applications +running on the local system via Unix sockets. Most importantly, this is the +mechanism by which the :manpage:`syslog(3)` call delivers syslog messages +to rsyslogd. + +.. seealso:: + + :doc:`omuxsock` + + +Notable Features +================ + +- :ref:`imuxsock-rate-limiting-label` +- :ref:`imuxsock-trusted-properties-label` +- :ref:`imuxsock-flow-control-label` +- :ref:`imuxsock-application-timestamps-label` +- :ref:`imuxsock-systemd-details-label` + + +Configuration Parameters +======================== + +.. note:: + + Parameter names are case-insensitive. + +Module Parameters +----------------- + +.. warning:: + + When running under systemd, **many "sysSock." parameters are ignored**. + See parameter descriptions and the :ref:`imuxsock-systemd-details-label` section for + details. + + +SysSock.IgnoreTimestamp +^^^^^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "on", "no", "``$SystemLogSocketIgnoreMsgTimestamp``" + +Ignore timestamps included in the messages, applies to messages received via +the system log socket. + + +SysSock.IgnoreOwnMessages +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "on", "no", "none" + +Ignores messages that originated from the same instance of rsyslogd. +There usually is no reason to receive messages from ourselves. This +setting is vital when writing messages to the systemd journal. + +.. versionadded:: 7.3.7 + +.. seealso:: + + See :doc:`omjournal <omjournal>` module documentation for a more + in-depth description. + + +SysSock.Use +^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "on", "no", "``$OmitLocalLogging``" + +Listen on the default local log socket (``/dev/log``) or, if provided, use +the log socket value assigned to the ``SysSock.Name`` parameter instead +of the default. This is most useful if you run multiple instances of +rsyslogd where only one shall handle the system log socket. Unless +disabled by the ``SysSock.Unlink`` setting, this socket is created +upon rsyslog startup and deleted upon shutdown, according to +traditional syslogd behavior. + +The behavior of this parameter is different for systemd systems. For those +systems, ``SysSock.Use`` still needs to be enabled, but the value of +``SysSock.Name`` is ignored and the socket provided by systemd is used +instead. If this parameter is *not* enabled, then imuxsock will only be +of use if a custom input is configured. + +See the :ref:`imuxsock-systemd-details-label` section for details. + + +SysSock.Name +^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "/dev/log", "no", "``$SystemLogSocketName``" + +Specifies an alternate log socket to be used instead of the default system +log socket, traditionally ``/dev/log``. Unless disabled by the +``SysSock.Unlink`` setting, this socket is created upon rsyslog startup +and deleted upon shutdown, according to traditional syslogd behavior. + +The behavior of this parameter is different for systemd systems. See the + :ref:`imuxsock-systemd-details-label` section for details. + + +SysSock.FlowControl +^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "``$SystemLogFlowControl``" + +Specifies if flow control should be applied to the system log socket. + + +SysSock.UsePIDFromSystem +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "``$SystemLogUsePIDFromSystem``" + +Specifies if the pid being logged shall be obtained from the log socket +itself. If so, the TAG part of the message is rewritten. It is recommended +to turn this option on, but the default is "off" to keep compatible +with earlier versions of rsyslog. + +.. versionadded:: 5.7.0 + + +SysSock.RateLimit.Interval +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "max", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "integer", "0", "", "no", "``$SystemLogRateLimitInterval``" + +Specifies the rate-limiting interval in seconds. Default value is 0, +which turns off rate limiting. Set it to a number of seconds (5 +recommended) to activate rate-limiting. The default of 0 has been +chosen as people experienced problems with this feature activated +by default. Now it needs an explicit opt-in by setting this parameter. + + +SysSock.RateLimit.Burst +^^^^^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "max", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "integer", "200", "(2^31)-1", "no", "``$SystemLogRateLimitBurst``" + +Specifies the rate-limiting burst in number of messages. + +.. versionadded:: 5.7.1 + + +SysSock.RateLimit.Severity +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "max", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "integer", "1", "", "no", "``$SystemLogRateLimitSeverity``" + +Specifies the severity of messages that shall be rate-limited. + +.. seealso:: + + https://en.wikipedia.org/wiki/Syslog#Severity_level + + +SysSock.UseSysTimeStamp +^^^^^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "on", "no", "``$SystemLogUseSysTimeStamp``" + +The same as the input parameter ``UseSysTimeStamp``, but for the system log +socket. This parameter instructs ``imuxsock`` to obtain message time from +the system (via control messages) instead of using time recorded inside +the message. This may be most useful in combination with systemd. Due to +the usefulness of this functionality, we decided to enable it by default. +As such, the behavior is slightly different than previous versions. +However, we do not see how this could negatively affect existing environments. + +.. versionadded:: 5.9.1 + + +SysSock.Annotate +^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "``$SystemLogSocketAnnotate``" + +Turn on annotation/trusted properties for the system log socket. See +the :ref:`imuxsock-trusted-properties-label` section for more info. + + +SysSock.ParseTrusted +^^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "``$SystemLogParseTrusted``" + +If ``SysSock.Annotation`` is turned on, create JSON/lumberjack properties +out of the trusted properties (which can be accessed via |FmtAdvancedName| +JSON Variables, e.g. ``$!pid``) instead of adding them to the message. + +.. versionadded:: 7.2.7 + |FmtAdvancedName| directive introduced + +.. versionadded:: 7.3.8 + |FmtAdvancedName| directive introduced + +.. versionadded:: 6.5.0 + |FmtObsoleteName| directive introduced + + +SysSock.Unlink +^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "on", "no", "none" + +If turned on (default), the system socket is unlinked and re-created +when opened and also unlinked when finally closed. Note that this +setting has no effect when running under systemd control (because +systemd handles the socket. See the :ref:`imuxsock-systemd-details-label` +section for details. + +.. versionadded:: 7.3.9 + + +SysSock.UseSpecialParser +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "on", "no", "none" + +The equivalent of the ``UseSpecialParser`` input parameter, but +for the system socket. If turned on (the default) a special parser is +used that parses the format that is usually used +on the system log socket (the one :manpage:`syslog(3)` creates). If set to +"off", the regular parser chain is used, in which case the format on the +log socket can be arbitrary. + +.. note:: + + When the special parser is used, rsyslog is able to inject a more precise + timestamp into the message (it is obtained from the log socket). If the + regular parser chain is used, this is not possible. + +.. versionadded:: 8.9.0 + The setting was previously hard-coded "on" + + +SysSock.ParseHostname +^^^^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "none" + +.. note:: + + This option only has an effect if ``SysSock.UseSpecialParser`` is + set to "off". + +Normally, the local log sockets do *not* contain hostnames. If set +to on, parsers will expect hostnames just like in regular formats. If +set to off (the default), the parser chain is instructed to not expect +them. + +.. versionadded:: 8.9.0 + + +Input Parameters +---------------- + +Ruleset +^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "string", "default ruleset", "no", "none" + +Binds specified ruleset to this input. If not set, the default +ruleset is bound. + +.. versionadded:: 8.17.0 + + +IgnoreTimestamp +^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "on", "no", "``$InputUnixListenSocketIgnoreMsgTimestamp``" + +Ignore timestamps included in messages received from the input being +defined. + + +IgnoreOwnMessages +^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "on", "no", "none" + +Ignore messages that originated from the same instance of rsyslogd. +There usually is no reason to receive messages from ourselves. This +setting is vital when writing messages to the systemd journal. + +.. versionadded:: 7.3.7 + +.. seealso:: + + See :doc:`omjournal <omjournal>` module documentation for a more + in-depth description. + + + + +FlowControl +^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "``$InputUnixListenSocketFlowControl``" + +Specifies if flow control should be applied to the input being defined. + + +RateLimit.Interval +^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "max", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "integer", "0", "", "no", "``$IMUXSockRateLimitInterval``" + +Specifies the rate-limiting interval in seconds. Default value is 0, which +turns off rate limiting. Set it to a number of seconds (5 recommended) +to activate rate-limiting. The default of 0 has been chosen as people +experienced problems with this feature activated by default. Now it +needs an explicit opt-in by setting this parameter. + + +RateLimit.Burst +^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "max", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "integer", "200", "(2^31)-1", "no", "``$IMUXSockRateLimitBurst``" + +Specifies the rate-limiting burst in number of messages. + +.. versionadded:: 5.7.1 + + +RateLimit.Severity +^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "max", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "integer", "1", "", "no", "``$IMUXSockRateLimitSeverity``" + +Specifies the severity of messages that shall be rate-limited. + +.. seealso:: + + https://en.wikipedia.org/wiki/Syslog#Severity_level + + +UsePIDFromSystem +^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "``$InputUnixListenSocketUsePIDFromSystem``" + +Specifies if the pid being logged shall be obtained from the log socket +itself. If so, the TAG part of the message is rewritten. It is +recommended to turn this option on, but the default is "off" to keep +compatible with earlier versions of rsyslog. + + +UseSysTimeStamp +^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "on", "no", "``$InputUnixListenSocketUseSysTimeStamp``" + +This parameter instructs ``imuxsock`` to obtain message time from +the system (via control messages) instead of using time recorded inside +the message. This may be most useful in combination with systemd. Due to +the usefulness of this functionality, we decided to enable it by default. +As such, the behavior is slightly different than previous versions. +However, we do not see how this could negatively affect existing environments. + +.. versionadded:: 5.9.1 + + +CreatePath +^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "``$InputUnixListenSocketCreatePath``" + +Create directories in the socket path if they do not already exist. +They are created with 0755 permissions with the owner being the +process under which rsyslogd runs. The default is not to create +directories. Keep in mind, though, that rsyslogd always creates +the socket itself if it does not exist (just not the directories +by default). + +This option is primarily considered useful for defining additional +sockets that reside on non-permanent file systems. As rsyslogd probably +starts up before the daemons that create these sockets, it is a vehicle +to enable rsyslogd to listen to those sockets even though their directories +do not yet exist. + +.. versionadded:: 4.7.0 +.. versionadded:: 5.3.0 + + +Socket +^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "string", "none", "no", "``$AddUnixListenSocket``" + +Adds additional unix socket. Formerly specified with the ``-a`` option. + + +HostName +^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "string", "NULL", "no", "``$InputUnixListenSocketHostName``" + +Allows overriding the hostname that shall be used inside messages +taken from the input that is being defined. + + +Annotate +^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "``$InputUnixListenSocketAnnotate``" + +Turn on annotation/trusted properties for the input that is being defined. +See the :ref:`imuxsock-trusted-properties-label` section for more info. + + +ParseTrusted +^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "``$ParseTrusted``" + +Equivalent to the ``SysSock.ParseTrusted`` module parameter, but applies +to the input that is being defined. + + +Unlink +^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "on", "no", "``none``" + +If turned on (default), the socket is unlinked and re-created when opened +and also unlinked when finally closed. Set it to off if you handle socket +creation yourself. + +.. note:: + + Note that handling socket creation oneself has the + advantage that a limited amount of messages may be queued by the OS + if rsyslog is not running. + +.. versionadded:: 7.3.9 + + +UseSpecialParser +^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "on", "no", "none" + +Equivalent to the ``SysSock.UseSpecialParser`` module parameter, but applies +to the input that is being defined. + +.. versionadded:: 8.9.0 + The setting was previously hard-coded "on" + + +ParseHostname +^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "none" + +Equivalent to the ``SysSock.ParseHostname`` module parameter, but applies +to the input that is being defined. + +.. versionadded:: 8.9.0 + + +.. _imuxsock-rate-limiting-label: + +Input rate limiting +=================== + +rsyslog supports (optional) input rate limiting to guard against the problems +of a wild running logging process. If more than +``SysSock.RateLimit.Interval`` \* ``SysSock.RateLimit.Burst`` log messages +are emitted from the same process, those messages with +``SysSock.RateLimit.Severity`` or lower will be dropped. It is not possible +to recover anything about these messages, but imuxsock will tell you how +many it has dropped once the interval has expired AND the next message is +logged. Rate-limiting depends on ``SCM\_CREDENTIALS``. If the platform does +not support this socket option, rate limiting is turned off. If multiple +sockets are configured, rate limiting works independently on each of +them (that should be what you usually expect). + +The same functionality is available for additional log sockets, in which +case the config statements just use the prefix RateLimit... but otherwise +works exactly the same. When working with severities, please keep in mind +that higher severity numbers mean lower severity and configure things +accordingly. To turn off rate limiting, set the interval to zero. + +.. versionadded:: 5.7.1 + + +.. _imuxsock-trusted-properties-label: + +Trusted (syslog) properties +=========================== + +rsyslog can annotate messages from system log sockets (via imuxsock) with +so-called `Trusted syslog +properties <http://www.rsyslog.com/what-are-trusted-properties/>`_, (or just +"Trusted Properties" for short). These are message properties not provided by +the logging client application itself, but rather obtained from the system. +As such, they can not be faked by the user application and are trusted in +this sense. This feature is based on a similar idea introduced in systemd. + +This feature requires a recent enough Linux Kernel and access to +the ``/proc`` file system. In other words, this may not work on all +platforms and may not work fully when privileges are dropped (depending +on how they are dropped). Note that trusted properties can be very +useful, but also typically cause the message to grow rather large. Also, +the format of log messages is changed by adding the trusted properties at +the end. For these reasons, the feature is **not enabled by default**. +If you want to use it, you must turn it on (via +``SysSock.Annotate`` and ``Annotate``). + +.. versionadded:: 5.9.4 + +.. seealso:: + + `What are "trusted properties"? + <http://www.rsyslog.com/what-are-trusted-properties/>`_ + + +.. _imuxsock-flow-control-label: + +Flow-control of Unix log sockets +================================ + +If processing queues fill up, the unix socket reader is blocked for a +short while to help prevent overrunning the queues. If the queues are +overrun, this may cause excessive disk-io and impact performance. + +While turning on flow control for many systems does not hurt, it `can` lead +to a very unresponsive system and as such is disabled by default. + +This means that log records are placed as quickly as possible into the +processing queues. If you would like to have flow control, you +need to enable it via the ``SysSock.FlowControl`` and ``FlowControl`` config +directives. Just make sure you have thought about the implications and have +tested the change on a non-production system first. + + +.. _imuxsock-application-timestamps-label: + +Control over application timestamps +=================================== + +Application timestamps are ignored by default. This is needed, as some +programs (e.g. sshd) log with inconsistent timezone information, what +messes up the local logs (which by default don't even contain time zone +information). This seems to be consistent with what sysklogd has done for +many years. Alternate behaviour may be desirable if gateway-like processes +send messages via the local log slot. In that case, it can be enabled via +the ``SysSock.IgnoreTimestamp`` and ``IgnoreTimestamp`` config directives. + + +.. _imuxsock-systemd-details-label: + +Coexistence with systemd +======================== + +Rsyslog should by default be configured for systemd support on all platforms +that usually run systemd (which means most Linux distributions, but not, for +example, Solaris). + +Rsyslog is able to coexist with systemd with minimal changes on the part of the +local system administrator. While the ``systemd journal`` now assumes full +control of the local ``/dev/log`` system log socket, systemd provides +access to logging data via the ``/run/systemd/journal/syslog`` log socket. +This log socket is provided by the ``syslog.socket`` file that is shipped +with systemd. + +The imuxsock module can still be used in this setup and provides superior +performance over :doc:`imjournal <imjournal>`, the alternative journal input +module. + +.. note:: + + It must be noted, however, that the journal tends to drop messages + when it becomes busy instead of forwarding them to the system log socket. + This is because the journal uses an async log socket interface for forwarding + instead of the traditional synchronous one. + +.. versionadded:: 8.32.0 + rsyslog emits an informational message noting the system log socket provided + by systemd. + +.. seealso:: + + :doc:`imjournal` + + +Handling of sockets +------------------- + +What follows is a brief description of the process rsyslog takes to determine +what system socket to use, which sockets rsyslog should listen on, whether +the sockets should be created and how rsyslog should handle the sockets when +shutting down. + +.. seealso:: + + `Writing syslog Daemons Which Cooperate Nicely With systemd + <https://www.freedesktop.org/wiki/Software/systemd/syslog/>`_ + + +Step 1: Select name of system socket +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. If the user has not explicitly chosen to set ``SysSock.Use="off"`` then + the default listener socket (aka, "system log socket" or simply "system + socket") name is set to ``/dev/log``. Otherwise, if the user `has` + explicitly set ``SysSock.Use="off"``, then rsyslog will not listen on + ``/dev/log`` OR any socket defined by the ``SysSock.Name`` parameter and + the rest of this section does not apply. + +#. If the user has specified ``sysSock.Name="/path/to/custom/socket"`` (and not + explicitly set ``SysSock.Use="off"``), then the default listener socket name + is overwritten with ``/path/to/custom/socket``. + +#. Otherwise, if rsyslog is running under systemd AND + ``/run/systemd/journal/syslog`` exists, (AND the user has not + explicitly set ``SysSock.Use="off"``) then the default listener socket name + is overwritten with ``/run/systemd/journal/syslog``. + + +Step 2: Listen on specified sockets +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + + This is true for all sockets, be it system socket or not. But if + ``SysSock.Use="off"``, the system socket will not be listened on. + +rsyslog evaluates the list of sockets it has been asked to activate: + +- the system log socket (if still enabled after completion of the last section) +- any custom inputs defined by the user + +and then checks to see if it has been passed in via systemd (name is checked). +If it was passed in via systemd, the socket is used as-is (e.g., not recreated +upon rsyslog startup), otherwise if not passed in via systemd the log socket +is unlinked, created and opened. + + +Step 3: Shutdown log sockets +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + + This is true for all sockets, be it system socket or not. + +Upon shutdown, rsyslog processes each socket it is listening on and evaluates +it. If the socket was originally passed in via systemd (name is checked), then +rsyslog does nothing with the socket (systemd maintains the socket). + +If the socket was `not` passed in via systemd AND the configuration permits +rsyslog to do so (the default setting), rsyslog will unlink/remove the log +socket. If not permitted to do so (the user specified otherwise), then rsyslog +will not unlink the log socket and will leave that cleanup step to the +user or application that created the socket to remove it. + + +Statistic Counter +================= + +This plugin maintains a global :doc:`statistics <../rsyslog_statistic_counter>` with the following properties: + +- ``submitted`` - total number of messages submitted for processing since startup + +- ``ratelimit.discarded`` - number of messages discarded due to rate limiting + +- ``ratelimit.numratelimiters`` - number of currently active rate limiters + (small data structures used for the rate limiting logic) + + +Caveats/Known Bugs +================== + +- When running under systemd, **many "sysSock." parameters are ignored**. + See parameter descriptions and the :ref:`imuxsock-systemd-details-label` section for + details. + +- On systems where systemd is used this module is often not loaded by default. + See the :ref:`imuxsock-systemd-details-label` section for details. + +- Application timestamps are ignored by default. See the + :ref:`imuxsock-application-timestamps-label` section for details. + +- `imuxsock does not work on Solaris + <http://www.rsyslog.com/why-does-imuxsock-not-work-on-solaris/>`_ + +.. todolist:: + + +Examples +======== + +Minimum setup +------------- + +The following sample is the minimum setup required to accept syslog +messages from applications running on the local system. + +.. code-block:: none + + module(load="imuxsock") + +This only needs to be done once. + + +Enable flow control +------------------- + +.. code-block:: none + :emphasize-lines: 2 + + module(load="imuxsock" # needs to be done just once + SysSock.FlowControl="on") # enable flow control (use if needed) + +Enable trusted properties +------------------------- + +As noted in the :ref:`imuxsock-trusted-properties-label` section, trusted properties +are disabled by default. If you want to use them, you must turn the feature +on via ``SysSock.Annotate`` for the system log socket and ``Annotate`` for +inputs. + +Append to end of message +^^^^^^^^^^^^^^^^^^^^^^^^ + +The following sample is used to activate message annotation and thus +trusted properties on the system log socket. These trusted properties +are appended to the end of each message. + +.. code-block:: none + :emphasize-lines: 2 + + module(load="imuxsock" # needs to be done just once + SysSock.Annotate="on") + + +Store in JSON message properties +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following sample is similar to the first one, but enables parsing of +trusted properties, which places the results into JSON/lumberjack variables. + +.. code-block:: none + :emphasize-lines: 2 + + module(load="imuxsock" + SysSock.Annotate="on" SysSock.ParseTrusted="on") + +Read log data from jails +------------------------ + +The following sample is a configuration where rsyslogd pulls logs from +two jails, and assigns different hostnames to each of the jails: + +.. code-block:: none + :emphasize-lines: 3,4,5 + + module(load="imuxsock") # needs to be done just once + input(type="imuxsock" + HostName="jail1.example.net" + Socket="/jail/1/dev/log") input(type="imuxsock" + HostName="jail2.example.net" Socket="/jail/2/dev/log") + +Read from socket on temporary file system +----------------------------------------- + +The following sample is a configuration where rsyslogd reads the openssh +log messages via a separate socket, but this socket is created on a +temporary file system. As rsyslogd starts up before the sshd daemon, it needs +to create the socket directories, because it otherwise can not open the +socket and thus not listen to openssh messages. + +.. code-block:: none + :emphasize-lines: 3,4 + + module(load="imuxsock") # needs to be done just once + input(type="imuxsock" + Socket="/var/run/sshd/dev/log" + CreatePath="on") + + +Disable rate limiting +--------------------- + +The following sample is used to turn off input rate limiting on the +system log socket. + +.. code-block:: none + :emphasize-lines: 2 + + module(load="imuxsock" # needs to be done just once + SysSock.RateLimit.Interval="0") # turn off rate limiting + |