mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-21 02:00:42 +01:00
201 lines
11 KiB
HTML
201 lines
11 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en">
|
|
<title>TCP Syslog Input Module</title>
|
|
</head>
|
|
|
|
<body>
|
|
<a href="rsyslog_conf_modules.html">back to rsyslog module overview</a>
|
|
|
|
<h1>TCP Syslog Input Module</h1>
|
|
<p><b>Module Name: imtcp</b></p>
|
|
<p><b>Author: </b>Rainer Gerhards <rgerhards@adiscon.com></p>
|
|
<p><b>Multi-Ruleset Support: </b>since 4.5.0 and 5.1.1
|
|
<p><b>Description</b>:</p>
|
|
<p>Provides the ability to receive syslog messages via TCP.
|
|
Encryption is natively provided by selecting the appropriate network stream driver and
|
|
can also be provided by using <a href="rsyslog_stunnel.html">stunnel</a>
|
|
(an alternative is the use the <a href="imgssapi.html">imgssapi</a> module).</p>
|
|
|
|
<p><b>Configuration Directives</b>:</p>
|
|
<p><b>Global Directives</b>:</p>
|
|
<ul>
|
|
<li><b>AddtlFrameDelimiter</b> <Delimiter><br>
|
|
This directive permits to specify an additional frame delimiter for plain tcp syslog.
|
|
The industry-standard specifies using the LF character as frame delimiter. Some vendors,
|
|
notable Juniper in their NetScreen products, use an invalid frame delimiter, in Juniper's
|
|
case the NUL character. This directive permits to specify the ASCII value of the delimiter
|
|
in question. Please note that this does not guarantee that all wrong implementations can
|
|
be cured with this directive. It is not even a sure fix with all versions of NetScreen,
|
|
as I suggest the NUL character is the effect of a (common) coding error and thus will
|
|
probably go away at some time in the future. But for the time being, the value 0 can
|
|
probably be used to make rsyslog handle NetScreen's invalid syslog/tcp framing.
|
|
For additional information, see this
|
|
<a href="http://kb.monitorware.com/problem-with-netscreen-log-t1652.html">forum thread</a>.
|
|
<br><b>If this doesn't work for you, please do not blame the rsyslog team. Instead file
|
|
a bug report with Juniper!</b>
|
|
<br>Note that a similar, but worse, issue exists with Cisco's IOS implementation. They do
|
|
not use any framing at all. This is confirmed from Cisco's side, but there seems to be
|
|
very limited interest in fixing this issue. This directive <b>can not</b> fix the Cisco bug.
|
|
That would require much more code changes, which I was unable to do so far. Full details
|
|
can be found at the <a href="http://www.rsyslog.com/Article321.phtml">Cisco tcp syslog anomaly</a>
|
|
page.
|
|
<li><b>DisableLFDelimiter</b> <on/<b>off</b>><br>
|
|
Industry-strandard plain text tcp syslog uses the LF to delimit syslog frames. However,
|
|
some users brought up the case that it may be useful to define a different delimiter and
|
|
totally disable LF as a delimiter (the use case named were multi-line messages). This mode
|
|
is non-standard and will probably come with a lot of problems. However, as there is need
|
|
for it and it is relatively easy to support, we do so. Be sure to turn this setting to
|
|
"on" only if you exactly know what you are doing. You may run into all sorts of troubles,
|
|
so be prepared to wrangle with that!
|
|
<li><b>NotifyOnConnectionClose</b> [on/<b>off</b>]<br>
|
|
instructs imtcp to emit a message if the remote peer closes a connection.<br>
|
|
<b>Important:</b> This directive is global to all listeners and must be given right
|
|
after loading imtcp, otherwise it may have no effect.</li>
|
|
<li><b>KeepAlive</b> <on/<b>off</b>><br>
|
|
enable of disable keep-alive packets at the tcp socket layer. The default is
|
|
to disable them.</li>
|
|
<li><b>FlowControl</b> <<b>on</b>/off><br>
|
|
This setting specifies whether some message flow control shall be exercised on the
|
|
related TCP input. If set to on, messages are handled as "light delayable", which means
|
|
the sender is throttled a bit when the queue becomes near-full. This is done in order
|
|
to preserve some queue space for inputs that can not throttle (like UDP), but it
|
|
may have some undesired effect in some configurations. Still, we consider this as
|
|
a useful setting and thus it is the default. To turn the handling off, simply
|
|
configure that explicitly.
|
|
</li>
|
|
<li><b>MaxListeners</b> <number><br>
|
|
Sets the maximum number of listeners (server ports) supported. Default is 20. This must be set before the first $InputTCPServerRun directive.</li>
|
|
<li><b>MaxSessions</b> <number><br> Sets the maximum number of sessions supported. Default is 200. This must be set before the first $InputTCPServerRun directive</li>
|
|
<li><b>StreamDriver.Name</b> <name><br>
|
|
Sets the driver name and overrides the system default. This enables e.g. to
|
|
define a system default of "gtls" (for TLS transmission) and override it to
|
|
"ptcp" (traditional unprotected plain tcp). Note, however, that this is a module
|
|
parameter. Currently, imtcp does not support mixed TLS/non-TLS listeners. If this
|
|
is desired, use imtcp for TLS, and imptcp for non-TLS. However, setting the
|
|
stream driver enables you to use e.g. plain tcp for the imtcp listeners while
|
|
setting the system default to TLS, which is then used by multiple forwarding (omfwd)
|
|
actions.
|
|
<li><b>StreamDriver.Mode</b> <number><br>
|
|
Sets the driver mode for the currently selected <a href="netstream.html">network stream driver</a>. <number> is driver specific.</li>
|
|
<li><b>StreamDriver.AuthMode</b> <mode-string><br>
|
|
Sets the authentication mode for the currently selected <a href="netstream.html">network stream driver</a>. <mode-string> is driver specifc.</li>
|
|
<li><b>PermittedPeer</b> <id-string><br>
|
|
Sets permitted peer IDs. Only these peers are able to connect to the
|
|
listener. <id-string> semantics depend on the currently selected
|
|
AuthMode and <a href="netstream.html">network stream driver</a>. PermittedPeer may not be set in anonymous modes.
|
|
<br>PermittedPeer may be set either to a single peer or an array of peers either of type IP or name, depending on the tls certificate.
|
|
<br>Single peer: PermittedPeer="127.0.0.1"
|
|
<br>Array of peers: PermittedPeer=["test1.example.net","10.1.2.3","test2.example.net","..."]</li>
|
|
</ul>
|
|
<p><b>Input Parameters</b>:</p>
|
|
<ul>
|
|
<li><b>Port</b> <port><br>
|
|
Starts a TCP server on selected port</li>
|
|
<li><b>Name</b> <name><br>
|
|
Sets a name for the inputname property. If no name is set "imtcp" is used by default. Setting a
|
|
name is not strictly necessary, but can be useful to apply filtering based on which input
|
|
the message was received from.
|
|
<li><b>Ruleset</b> <ruleset><br>
|
|
Binds the listener to a specific <a href="multi_ruleset.html">ruleset</a>.</li>
|
|
<li><b>SupportOctetCountedFraming</b> <<b>on</b>|off><br>
|
|
If set to "on", the legacy octed-counted framing (similar to RFC5425 framing) is
|
|
activated. This is the default and should be left unchanged until you know
|
|
very well what you do. It may be useful to turn it off, if you know this framing
|
|
is not used and some senders emit multi-line messages into the message stream.
|
|
</li>
|
|
<li><b>defaultTZ</b> <timezone-info><br>
|
|
This is an <b>experimental</b> parameter; details may change at any time and it may
|
|
also be discoutinued without any early warning.<br>
|
|
Permits to set a default timezone for this listener. This is useful when working with
|
|
legacy syslog (RFC3164 et al) residing in different timezones. If set it will be used as
|
|
timezone for all messages <b>that do not contain timezone info</b>.
|
|
Currently, the format <b>must</b> be "+/-hh:mm", e.g. "-05:00", "+01:30". Other formats,
|
|
including TZ names (like EST) are NOT yet supported. Note that consequently no daylight
|
|
saving settings are evaluated when working with timezones. If an invalid format is used,
|
|
"interesting" things can happen, among them malformed timestamps and rsyslogd segfaults.
|
|
This will obviously be changed at the time this feature becomes non-experimental.</li>
|
|
<li><b>RateLimit.Interval</b> [number] - (available since 7.3.1) 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.
|
|
</li>
|
|
<li><b>RateLimit.Burst</b> [number] - (available since 7.3.1) specifies the rate-limiting
|
|
burst in number of messages. Default is 10,000.
|
|
</li>
|
|
</ul>
|
|
<b>Caveats/Known Bugs:</b>
|
|
<ul>
|
|
<li>module always binds to all interfaces</li>
|
|
<li>can not be loaded together with <a href="imgssapi.html">imgssapi</a>
|
|
(which includes the functionality of imtcp)</li>
|
|
</ul>
|
|
<p><b>Example:</b></p>
|
|
<p>This sets up a TCP server on port 514 and permits it to accept up to 500 connections:<br>
|
|
</p>
|
|
<textarea rows="15" cols="60">module(load="imtcp" MaxSessions="500")
|
|
input(type="imtcp" port="514")
|
|
</textarea>
|
|
<p>Note that the global parameters (here: max sessions) need to be set when the module is loaded. Otherwise, the parameters will not apply.
|
|
</p>
|
|
|
|
<p><b>Legacy Configuration Directives</b>:</p>
|
|
<ul>
|
|
<li><b>$InputTCPServerAddtlFrameDelimiter <Delimiter></b><br>
|
|
equivalent to: AddtlFrameDelimiter
|
|
<li><b>$InputTCPServerDisableLFDelimiter</b> <on/<b>off</b>> (available since 5.5.3)<br>
|
|
equivalent to: DisableLFDelimiter
|
|
<li><b>$InputTCPServerNotifyOnConnectionClose</b> [on/<b>off</b>] (available since 4.5.5)<br>
|
|
equivalent to: NotifyOnConnectionClose<br>
|
|
</li>
|
|
<li><b>$InputTCPServerKeepAlive</b> <on/<b>off</b>><br>
|
|
equivalent to: KeepAlive</li>
|
|
<li><b>$InputTCPServerRun</b> <port><br>
|
|
equivalent to: Port</li>
|
|
<li><b>$InputTCPFlowControl</b> <<b>on</b>/off><br>
|
|
equivalent to: FlowControl
|
|
</li>
|
|
<li><b>$InputTCPMaxListeners</b> <number><br>
|
|
equivalent to: MaxListeners</li>
|
|
<li><b>$InputTCPMaxSessions</b> <number><br>
|
|
equivalent to: MaxSessions</li>
|
|
<li><b>$InputTCPServerStreamDriverMode</b> <number><br>
|
|
equivalent to: StreamDriver.Mode</li>
|
|
<li><b>$InputTCPServerInputName</b> <name><br>
|
|
equivalent to: Name
|
|
<li><b>$InputTCPServerStreamDriverAuthMode</b> <mode-string><br>
|
|
equivalent to: StreamDriver.AuthMode</li>
|
|
<li><b>$InputTCPServerStreamDriverPermittedPeer</b> <id-string><br>
|
|
equivalent to: PermittedPeer.</li>
|
|
<li><b>$InputTCPServerBindRuleset</b> <ruleset><br>
|
|
equivalent to: Ruleset</a>.</li>
|
|
<li><b>$InputTCPSupportOctetCountedFraming</b> <<b>on</b>|off><br>
|
|
equivalent to: SupportOctetCountedFraming
|
|
</li>
|
|
</ul>
|
|
<b>Caveats/Known Bugs:</b>
|
|
<ul>
|
|
<li>module always binds to all interfaces</li>
|
|
<li>can not be loaded together with <a href="imgssapi.html">imgssapi</a>
|
|
(which includes the functionality of imtcp)</li>
|
|
</ul>
|
|
<p><b>Example:</b></p>
|
|
<p>This sets up a TCP server on port 514 and permits it to accept up to 500 connections:<br>
|
|
</p>
|
|
<textarea rows="15" cols="60">$ModLoad imtcp # needs to be done just once
|
|
$InputTCPMaxSessions 500
|
|
$InputTCPServerRun 514
|
|
</textarea>
|
|
<p>Note that the parameters (here: max sessions) need to be set <b>before</b> the listener
|
|
is activated. Otherwise, the parameters will not apply.
|
|
</p>
|
|
<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,2009 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>
|