1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
<!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>
|
