============================================================= imuxsock: Unix Socket Input Module (parameter headers format) ============================================================= =========================== =========================================================================== **Module Name:**  **imuxsock** **Author:** `Rainer Gerhards `_ =========================== =========================================================================== ------- 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:`rate-limiting-label-parameter-headers` - :ref:`trusted-properties-label-parameter-headers` - :ref:`flow-control-label-parameter-headers` - :ref:`application-timestamps-label-parameter-headers` - :ref:`systemd-details-label-parameter-headers` ------------------------ Configuration Parameters ------------------------ .. note:: Parameter names are case-insensitive. Global Parameters ================= .. warning:: When running under systemd, **many "sysSock." parameters are ignored**. See parameter descriptions and the :ref:`systemd-details-label-parameter-headers` section for details. SysSock.IgnoreTimestamp ----------------------- ====== ======= ========= type default mandatory ====== ======= ========= binary on no ====== ======= ========= Ignore timestamps included in the messages, applies to messages received via the system log socket. SysSock.IgnoreOwnMessages ------------------------- ====== ======= ========= type default mandatory ====== ======= ========= binary on no ====== ======= ========= .. versionadded:: 7.3.7 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 Linux journal. .. seealso:: See :doc:`omjournal ` module documentation for a more in-depth description. SysSock.Use ----------- ====== ======= ========= type default mandatory ====== ======= ========= binary on no ====== ======= ========= 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:`systemd-details-label-parameter-headers` section for details. SysSock.Placeholder1 -------------------- ======= ======= ========= type default mandatory ======= ======= ========= chaotic haha maybe ======= ======= ========= Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus dapibus nulla sit amet porta iaculis. Ut auctor diam eget sem fermentum, sit amet tincidunt libero consectetur. Curabitur id sem tortor. Curabitur mattis eleifend orci eget vehicula. Donec aliquam a purus nec lacinia. In fringilla turpis et enim efficitur, in porttitor neque fringilla. In consequat id purus vitae elementum. Sed sit amet hendrerit purus. Nulla egestas nisl odio, nec pharetra felis ullamcorper ut. Quisque ac arcu rutrum, efficitur quam eu, placerat arcu. Morbi quis purus turpis. Cras et lobortis tortor. Nam malesuada orci risus, nec eleifend eros rhoncus et. Quisque auctor dignissim suscipit. Donec eleifend sit amet libero fringilla laoreet. SysSock.Placeholder2 -------------------- ======= ======= ========= type default mandatory ======= ======= ========= chaotic haha maybe ======= ======= ========= Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae diam vel dui efficitur molestie. Cras leo mi, mattis nec ornare a, pellentesque in magna. Phasellus massa ex, imperdiet id convallis non, lacinia sed purus. Quisque ut vulputate quam. Etiam vitae suscipit erat. Donec fringilla bibendum libero non efficitur. Praesent volutpat massa leo. Sed semper cursus augue, nec rhoncus libero pellentesque eu. Curabitur rutrum urna quis pharetra fermentum. Nam at leo non enim auctor pharetra. Nullam nisl massa, volutpat eget ante quis, lacinia dapibus lacus. Aliquam sodales, dolor sed laoreet finibus, urna urna scelerisque arcu, et pretium ipsum risus at tortor. SysSock.Placeholder3 -------------------- ======= ======= ========= type default mandatory ======= ======= ========= chaotic haha maybe ======= ======= ========= Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent sit amet magna ipsum. Integer nec lorem turpis. Nam feugiat fermentum urna, sed bibendum nunc consectetur id. Suspendisse eu velit felis. Pellentesque luctus orci eget nulla porta accumsan. Morbi vulputate sem et dui efficitur pellentesque. Vivamus ultrices, libero at aliquet interdum, erat eros semper urna, vel molestie elit leo nec diam. Curabitur et velit magna. Donec cursus, magna et cursus faucibus, lectus dolor eleifend ligula, nec sollicitudin velit libero sit amet eros. Nulla ac tortor sed metus aliquam vulputate. Nam vitae vestibulum diam. Sed vestibulum fringilla leo, quis eleifend odio imperdiet dictum. Nulla mi ante, tincidunt in eros in, fringilla iaculis magna. Lorem ipsum dolor sit amet, consectetur adipiscing elit. SysSock.Placeholder4 -------------------- ======= ======= ========= type default mandatory ======= ======= ========= chaotic haha maybe ======= ======= ========= Nulla ultricies odio non mi tincidunt faucibus. Donec sit amet fringilla sapien. Nunc facilisis ex vestibulum diam rutrum, vel feugiat neque imperdiet. Proin purus mi, egestas fermentum libero at, egestas eleifend lorem. Proin eu risus a est luctus condimentum. Aliquam suscipit odio vel mauris fermentum finibus. Duis nibh ex, pretium vitae convallis volutpat, ullamcorper ut enim. Aliquam sed aliquam erat. Pellentesque sed finibus ligula. Integer cursus arcu ac libero venenatis, in aliquam ante volutpat. Quisque at eros sed turpis malesuada pharetra eget eu ex. Donec suscipit, est tincidunt vehicula ultrices, neque nibh dictum lorem, id dictum arcu neque in nisi. Nulla suscipit mi sed libero pretium, sed ultrices massa tincidunt. In in elit sed ex dictum vulputate. Nunc non purus dui. Quisque efficitur libero eu velit vulputate, a sollicitudin libero congue. Input Parameters ================ Placeholder1 ------------ ======= ======= ========= type default mandatory ======= ======= ========= chaotic haha maybe ======= ======= ========= Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum ullamcorper lacus viverra, euismod massa a, blandit urna. Quisque erat orci, convallis sagittis cursus vulputate, aliquam quis elit. Suspendisse mollis enim dignissim imperdiet egestas. Suspendisse vitae felis nisi. Phasellus condimentum dapibus velit, eget placerat ante fringilla ut. Suspendisse convallis sapien vitae felis auctor, vitae mollis nibh sodales. Quisque vitae ex sit amet felis posuere euismod. Cras interdum, ligula non euismod faucibus, arcu nunc tempor neque, ut sodales sapien risus sit amet eros. Phasellus placerat lorem nec felis tincidunt, eu dapibus dui volutpat. Placeholder2 ------------ ======= ======= ========= type default mandatory ======= ======= ========= chaotic haha maybe ======= ======= ========= Pellentesque at tellus id lacus maximus rutrum. Nam a convallis ligula, ut semper dolor. Duis non diam et magna tincidunt ornare. Cras quis sem egestas, iaculis leo eget, elementum mi. Vivamus posuere magna eu condimentum ultricies. Quisque venenatis metus at interdum bibendum. Proin iaculis tempor leo, et posuere est hendrerit ut. Praesent sed porta enim. Pellentesque vehicula laoreet purus, sit amet lacinia odio sagittis eu. Vestibulum aliquet magna egestas, lobortis dolor vel, scelerisque libero. Duis orci risus, vehicula eu lacus ac, sagittis feugiat ex. Proin eget sapien ultrices, lobortis odio id, iaculis enim. Vestibulum faucibus turpis est, at egestas velit dapibus vitae. Morbi eu augue lectus. Donec rutrum neque sit amet pharetra tristique. Vivamus tempor ornare mi et bibendum. Placeholder3 ------------ ======= ======= ========= type default mandatory ======= ======= ========= chaotic haha maybe ======= ======= ========= Quisque tincidunt ipsum sed tincidunt tempor. Etiam diam enim, placerat nec justo vel, ultrices tincidunt arcu. Sed feugiat magna sed convallis volutpat. Quisque convallis turpis eget blandit suscipit. Cras id mauris sed nisl vehicula posuere. Sed feugiat pretium bibendum. Nam porta ipsum et metus commodo dapibus. Aenean sed tellus consectetur, cursus leo sit amet, euismod velit. Maecenas ac velit eleifend, gravida arcu vitae, molestie eros. Praesent tortor dui, condimentum nec diam in, iaculis iaculis nunc. Nam ac leo semper, vulputate ex sit amet, tincidunt lacus. Aliquam viverra pretium sagittis. Placeholder4 ------------ ======= ======= ========= type default mandatory ======= ======= ========= chaotic haha maybe ======= ======= ========= Nullam eget urna nec nisl bibendum sagittis. Cras at pretium risus. Sed aliquam nisi orci, eget placerat metus ultricies in. Fusce tortor lectus, viverra ut metus sit amet, pharetra viverra est. Nam nec dui interdum, faucibus massa ut, pretium quam. Maecenas condimentum tempor tellus, id imperdiet est luctus fringilla. Duis vehicula, nibh sed porta finibus, ex ipsum viverra nunc, varius sagittis dui ex vitae sem. Praesent nec lectus quis lectus vestibulum mollis et a odio. Suspendisse ut augue nec purus venenatis eleifend nec venenatis massa. Ut ac turpis commodo, aliquet neque id, porttitor massa. In ultrices elementum tincidunt. Pellentesque non dapibus felis. Ut pharetra quam nec mi malesuada, vulputate dictum nisl semper. .. _rate-limiting-label-parameter-headers: ------------------- Input rate limiting ------------------- .. versionadded:: 5.7.1 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. .. _trusted-properties-label-parameter-headers: --------------------------- Trusted (syslog) properties --------------------------- .. versionadded:: 5.9.4 rsyslog can annotate messages from system log sockets (via imuxsock) with so-called `Trusted syslog 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``). .. seealso:: `What are "trusted properties"? `_ .. _flow-control-label-parameter-headers: -------------------------------- 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. .. _application-timestamps-label-parameter-headers: ----------------------------------- 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. .. _systemd-details-label-parameter-headers: ------------------------ 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 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. .. versionadded:: 8.32.0 rsyslog emits an informational message noting the system log socket provided by systemd. The imuxsock module can still be used in this setup and provides superior performance over :doc:`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. .. 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 `_ 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 (smal data structures used for the rate limiting logic) ------------------ Caveats/Known Bugs ------------------ - There is a compile-time limit of 50 concurrent sockets. If you need more, you need to change the array size in ``imuxsock.c``. - When running under systemd, **many "sysSock." parameters are ignored**. See parameter descriptions and the :ref:`systemd-details-label-parameter-headers` section for details. - On systems where systemd is used this module is often not loaded by default. See the :ref:`systemd-details-label-parameter-headers` section for details. - Application timestamps are ignored by default. See the :ref:`application-timestamps-label-parameter-headers` section for details. - `imuxsock does 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:`trusted-properties-label-parameter-headers` 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 similiar 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