Adding upstream version 8.2402.0+dfsg.upstream/8.2402.0+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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
+