mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-17 19:50:41 +01:00
d6da57ae03
Conflicts: action.c configure.ac doc/imuxsock.html plugins/imklog/imklog.c plugins/imptcp/imptcp.c plugins/imtcp/imtcp.c plugins/imudp/imudp.c plugins/imuxsock/imuxsock.c runtime/glbl.c runtime/glbl.h runtime/net.c runtime/ruleset.c tcpsrv.h tools/syslogd.c
196 lines
12 KiB
HTML
196 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html><head>
|
|
<meta http-equiv="Content-Language" content="en">
|
|
<title>Unix Socket Input</title>
|
|
</head>
|
|
<body>
|
|
<a href="rsyslog_conf_modules.html">back</a>
|
|
|
|
<h1>Unix Socket Input</h1>
|
|
<p><b>Module Name: imuxsock</b></p>
|
|
<p><b>Author: </b>Rainer Gerhards
|
|
<rgerhards@adiscon.com></p>
|
|
<p><b>Description</b>:</p>
|
|
<p><b>Provides the ability to accept syslog messages via local Unix
|
|
sockets. Most importantly, this is the mechanism by which the syslog(3)
|
|
call delivers syslog messages to rsyslogd.</b> So you need to have this
|
|
module loaded to read the system log socket and be able to process log
|
|
messages from applications running on the local system.</p>
|
|
<p><b>Application-provided
|
|
timestamps are ignored by default.</b> 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 did for
|
|
the past four years. Alternate behaviour may be desirable if
|
|
gateway-like processes send messages via the local log slot - in this
|
|
case, it can be enabled via the
|
|
$InputUnixListenSocketIgnoreMsgTimestamp and $SystemLogSocketIgnoreMsgTimestamp config directives</p>
|
|
<p><b>There is input rate limiting available,</b> (since 5.7.1) to guard you against
|
|
the problems of a wild running logging process.
|
|
If more than $SystemLogRateLimitInterval * $SystemLogRateLimitBurst log messages are emitted
|
|
from the same process, those messages with $SystemLogRateLimitSeverity 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 one 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 $IMUXSockRateLimit... 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.
|
|
<p><b>Unix log sockets can be flow-controlled.</b> That is, if processing queues fill up,
|
|
the unix socket reader is blocked for a short while. This may be useful to prevent overruning
|
|
the queues (which may cause exessive disk-io where it actually would not be needed). However,
|
|
flow-controlling a log socket (and especially the system log socket) can lead to a very
|
|
unresponsive system. As such, flow control is disabled by default. That means any log records
|
|
are places as quickly as possible into the processing queues. If you would like to have
|
|
flow control, you need to enable it via the $SystemLogSocketFlowControl and
|
|
$InputUnixListenSocketFlowControl config directives. Just make sure you thought about
|
|
the implications. Note that for many systems, turning on flow control does not hurt.
|
|
<p>Starting with rsyslog 5.9.4,
|
|
<b><a href="http://www.rsyslog.com/what-are-trusted-properties/">trusted syslog properties</a>
|
|
are available</b>. These require 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 obviously changed by adding the trusted properties at the end.
|
|
For these reasons, the feature is <b>not enabled by default</b>. If you want to use it,
|
|
you must turn it on (via $SystemLogSocketAnnotate and $InputUnixListenSocketAnnotate).
|
|
<p><b>Configuration Directives</b>:</p>
|
|
<ul>
|
|
<li><b>$InputUnixListenSocketIgnoreMsgTimestamp</b> [<b>on</b>/off]
|
|
<br>Ignore timestamps included in the message. Applies to the next socket being added.</li>
|
|
<li><b>$InputUnixListenSocketFlowControl</b> [on/<b>off</b>] - specifies if flow control should be applied
|
|
to the next socket.</li>
|
|
<li><b>$IMUXSockRateLimitInterval</b> [number] - 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 choosen in 5.9.6+,
|
|
as people experienced problems with this feature activated by default. Now it needs an
|
|
explicit opt-in by setting this parameter.
|
|
</li>
|
|
<li><b>$IMUXSockRateLimitBurst</b> [number] - specifies the rate-limiting
|
|
burst in number of messages. Default is 200.
|
|
</li>
|
|
<li><b>$IMUXSockRateLimitSeverity</b> [numerical severity] - specifies the severity of
|
|
messages that shall be rate-limited.
|
|
</li>
|
|
<li><b>$IMUXSockLocalIPIF</b> [interface name] - (available since 5.9.6) - if provided, the IP of the specified
|
|
interface (e.g. "eth0") shall be used as fromhost-ip for imuxsock-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.
|
|
</li>
|
|
<li><b>$InputUnixListenSocketUsePIDFromSystem</b> [on/<b>off</b>] - 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. This option was introduced in 5.7.0.</li>
|
|
<li><b>$InputUnixListenSocketUseSysTimeStamp</b> [<b>on</b>/off] instructs imuxsock
|
|
to obtain message time from the system (via control messages) insted of using time
|
|
recorded inside the message. This may be most useful in combination with systemd. Note:
|
|
this option was introduced with version 5.9.1. Due to the usefulness of it, we
|
|
decided to enable it by default. As such, 5.9.1 and above behave slightly different
|
|
than previous versions. However, we do not see how this could negatively affect
|
|
existing environments.<br>
|
|
<li><b>$SystemLogSocketIgnoreMsgTimestamp</b> [<b>on</b>/off]<br>
|
|
Ignore timestamps included in the messages, applies to messages received via the system log socket.</li>
|
|
<li><b>$OmitLocalLogging</b> (imuxsock) [on/<b>off</b>] -- former -o option;
|
|
do NOT listen for the local log socket. This is most useful if you run multiple
|
|
instances of rsyslogd where only one shall handle the system log socket.</li>
|
|
<li><b>$SystemLogSocketName</b> <name-of-socket> -- former -p option</li>
|
|
<li><b>$SystemLogFlowControl</b> [on/<b>off</b>] - specifies if flow control should be applied
|
|
to the system log socket.</li>
|
|
<li><b>$SystemLogUsePIDFromSystem</b> [on/<b>off</b>] - 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. This option was introduced in 5.7.0.</li>
|
|
<li><b>$SystemLogRateLimitInterval</b> [number] - specifies the rate-limiting
|
|
interval in seconds. Default value is 5 seconds. Set it to 0 to turn rate limiting off.
|
|
</li>
|
|
<li><b>$SystemLogRateLimitBurst</b> [number] - specifies the rate-limiting
|
|
burst in number of messages. Default is 200.
|
|
</li>
|
|
<li><b>$SystemLogRateLimitSeverity</b> [numerical severity] - specifies the severity of
|
|
messages that shall be rate-limited.
|
|
</li>
|
|
<li><b>$SystemLogUseSysTimeStamp</b> [<b>on</b>/off] the same as $InputUnixListenSocketUseSysTimeStamp, but for the system log socket.
|
|
<li><b>$InputUnixListenSocketCreatePath</b> [on/<b>off</b>] - 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).
|
|
<br>Note that this statement affects the
|
|
next $AddUnixListenSocket directive that follows in sequence in the configuration file. It never works
|
|
on the system log socket (where it is deemed unnecessary). Also note that it is automatically
|
|
being reset to "off" after the $AddUnixListenSocket directive, so if you would have it active
|
|
for two additional listen sockets, you need to specify it in front of each one. 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. [available since 4.7.0 and 5.3.0]</li>
|
|
<li><b>$AddUnixListenSocket</b> <name-of-socket> adds additional unix socket, default none -- former -a option</li>
|
|
<li><b>$InputUnixListenSocketHostName</b> <hostname> permits to override the hostname that
|
|
shall be used inside messages taken from the <b>next</b> $AddUnixListenSocket socket. Note that
|
|
the hostname must be specified before the $AddUnixListenSocket configuration directive, and it
|
|
will only affect the next one and then automatically be reset. This functionality is provided so
|
|
that the local hostname can be overridden in cases where that is desired.</li>
|
|
<li><b>$InputUnixListenSocketAnnotate</b> <on/<b>off</b>> turn on annotation/trusted
|
|
properties for the non-system log socket in question.</li>
|
|
<li><b>$SystemLogSocketAnnotate</b> <on/<b>off</b>> turn on annotation/trusted
|
|
properties for the system log socket.</li>
|
|
</ul>
|
|
|
|
<b>Caveats/Known Bugs:</b><br>
|
|
<ul>
|
|
<li>There is a compile-time limit of 50 concurrent sockets. If you need more, you need to
|
|
change the array size in imuxsock.c.
|
|
<li>This documentation is sparse and incomplete.
|
|
</ul>
|
|
<p><b>Sample:</b></p>
|
|
<p>The following sample is the minimum setup required to accept syslog messages from applications running
|
|
on the local system.<br>
|
|
</p>
|
|
<textarea rows="2" cols="70">$ModLoad imuxsock # needs to be done just once
|
|
$SystemLogSocketFlowControl on # enable flow control (use if needed)
|
|
</textarea>
|
|
<p>The following sample is a configuration where rsyslogd pulls logs from two
|
|
jails, and assigns different hostnames to each of the jails: </p>
|
|
<textarea rows="6" cols="70">$ModLoad imuxsock # needs to be done just once
|
|
|
|
$InputUnixListenSocketHostName jail1.example.net
|
|
$AddUnixListenSocket /jail/1/dev/log
|
|
$InputUnixListenSocketHostName jail2.example.net
|
|
$AddUnixListenSocket /jail/2/dev/log
|
|
</textarea>
|
|
<p>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, it needs to create the socket
|
|
directories, because it otherwise can not open the socket and thus not listen
|
|
to openssh messages. Note that it is vital not to place any other socket between
|
|
the $InputUnixListenSocketCreatePath and the $InputUnixListenSocketHostName.</p>
|
|
<textarea rows="6" cols="70">$ModLoad imuxsock # needs to be done just once
|
|
|
|
$InputUnixListenSocketCreatePath on # turn on for *next* socket
|
|
$InputUnixListenSocketHostName /var/run/sshd/dev/log
|
|
</textarea>
|
|
<p>The following sample is used to turn off input rate limiting on the system log
|
|
socket.
|
|
<textarea rows="4" cols="70">$ModLoad imuxsock # needs to be done just once
|
|
|
|
$SystemLogRateLimitInterval 0 # turn off rate limiting
|
|
</textarea>
|
|
<p>The following sample is used activate message annotation and thus trusted properties
|
|
on the system log socket.
|
|
<textarea rows="4" cols="70">$ModLoad imuxsock # needs to be done just once
|
|
|
|
$SystemLogSocketAnnotate on
|
|
</textarea>
|
|
<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>]
|
|
[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
|
|
<p><font size="2">This documentation is part of the
|
|
<a href="http://www.rsyslog.com/">rsyslog</a>
|
|
project.<br>
|
|
Copyright © 2008-2012 by <a href="http://www.gerhards.net/rainer">Rainer
|
|
Gerhards</a> and
|
|
<a href="http://www.adiscon.com/">Adiscon</a>.
|
|
Released under the GNU GPL version 3 or higher.</font></p>
|
|
</body></html>
|