diff options
Diffstat (limited to 'doc/imuxsock.html')
| -rw-r--r-- | doc/imuxsock.html | 84 |
1 files changed, 79 insertions, 5 deletions
diff --git a/doc/imuxsock.html b/doc/imuxsock.html index 472470a0..ee5db22d 100644 --- a/doc/imuxsock.html +++ b/doc/imuxsock.html @@ -25,6 +25,21 @@ 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, @@ -40,12 +55,50 @@ the implications. Note that for many systems, turning on flow control does not h <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 5 seconds. Set it to 0 to turn rate limiting off. +</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>$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>$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</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>$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 @@ -54,29 +107,50 @@ will only affect the next one and then automatically be reset. This functionalit that the local hostname can be overridden in cases where that is desired.</li> </ul> <b>Caveats/Known Bugs:</b><br> -<br> -This documentation is sparse and incomplete. +<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>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="60">$ModLoad imuxsock # needs to be done just once +<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="6" cols="70">$ModLoad imuxsock # needs to be done just once + +$SystemLogRateLimitInterval 0 # turn off rate limiting +</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 by <a href="http://www.gerhards.net/rainer">Rainer +Copyright © 2008-2010 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> |