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
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
|
<!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
IgnoreTimestamp and SysSock.IgnoreTimestamp 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 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 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 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.
<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 SysSock.FlowControl and
FlowControl 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 SysSock.Annotate and Annotate).
<p><b>Configuration Directives</b>:</p>
<p><b>Global Parameters</b></p>
<ul>
<li><b>SysSock.IgnoreTimestamp</b> [<b>on</b>/off]<br>
Ignore timestamps included in the messages, applies to messages received via the system log socket.
</li>
<li><b>SysSock.IgnoreOwnMessages</b> [<b>on</b>/off] (available since 7.3.7)<br>
Ignores messages that originated from the same instance of rsyslogd. There usually
is no reason to receive messages from ourselfs. This setting is vital
when writing messages to the Linux journal. See <a href="omjournal.html">omjournal</a>
module documentation for a more in-depth description.
</li>
<li><b>SysSock.Use</b> (imuxsock) [on/<b>off</b>]
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>SysSock.Name</b> <name-of-socket>
</li>
<li><b>SysSock.FlowControl</b> [on/<b>off</b>] - specifies if flow control should be applied
to the system log socket.
</li>
<li><b>SysSock.UsePIDFromSystem</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.
</li>
<li><b>SysSock.RateLimit.Interval</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>SysSock.RateLimit.Burst</b> [number] - specifies the rate-limiting
burst in number of messages. Default is 200.
</li>
<li><b>SysSock.RateLimit.Severity</b> [numerical severity] - specifies the severity of
messages that shall be rate-limited.
</li>
<li><b>SysSock.UseSysTimeStamp</b> [<b>on</b>/off] the same as $InputUnixListenSocketUseSysTimeStamp, but for the system log socket.
</li>
<li><b>SysSock.Annotate</b> <on/<b>off</b>> turn on annotation/trusted
properties for the system log socket.</li>
<li><b>SysSock.ParseTrusted</b> <on/<b>off</b>> if Annotation is turned on, create
JSON/lumberjack properties out of the trusted properties (which can be accessed
via RainerScript JSON Variables, e.g. "$!pid") instead of adding them to the message.
</li>
</ul>
<p><b>Input Instance Parameters</b></p>
<ul>
<li><b>IgnoreTimestamp</b> [<b>on</b>/off]
<br>Ignore timestamps included in the message. Applies to the next socket being added.</li>
<li><b>IgnoreOwnMessages</b> [<b>on</b>/off] (available since 7.3.7)<br>
Ignore messages that originated from the same instance of rsyslogd. There usually
is no reason to receive messages from ourselfs. This setting is vital
when writing messages to the Linux journal. See <a href="omjournal.html">omjournal</a>
module documentation for a more in-depth description.
</li>
<li><b>FlowControl</b> [on/<b>off</b>] - specifies if flow control should be applied
to the next socket.</li>
<li><b>RateLimit.Interval</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
as people experienced problems with this feature activated by default. Now it needs an
explicit opt-in by setting this parameter.
</li>
<li><b>RateLimit.Burst</b> [number] - specifies the rate-limiting
burst in number of messages. Default is 200.
</li>
<li><b>RateLimit.Severity</b> [numerical severity] - specifies the severity of
messages that shall be rate-limited.
</li>
<!--<li><b>LocalIPIF</b> [interface name] - 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>UsePIDFromSystem</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. </li>
<li><b>UseSysTimeStamp</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>CreatePath</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 Socket 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 Socket 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.</li>
<li><b>Socket</b> <name-of-socket> adds additional unix socket, default none -- former -a option</li>
<li><b>HostName</b> <hostname> permits to override the hostname that
shall be used inside messages taken from the <b>next</b> Socket 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>Annotate</b> <on/<b>off</b>> turn on annotation/trusted
properties for the non-system log socket in question.</li>
<li><b>ParseTrusted</b> <on/<b>off</b>> equivalent to the SysSock.ParseTrusted module
parameter, but applies to the input that is being defined.
</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">module(load="imuxsock" # needs to be done just once
SysSock.FlowControl="on") # enable flow control (use if needed)
</textarea>
<p>The following sample is similiar to the first one, but enables trusted
properties, which are put into JSON/lumberjack variables.
<br>
</p>
<textarea rows="2" cols="70">module(load="imuxsock" SysSock.Annotate="on" SysSock.ParseTrusted="on")
</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">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")
</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 CreatePath and the Socket.</p>
<textarea rows="6" cols="70">module(load="imuxsock") # needs to be done just once
input(type="imuxsock" Socket="/var/run/sshd/dev/log" CreatePath="on")
</textarea>
<p>The following sample is used to turn off input rate limiting on the system log
socket.
<textarea rows="4" cols="70">module(load="imuxsock" # needs to be done just once
SysSock.RateLimit.Interval="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">module(load="imuxsock" # needs to be done just once
SysSock.Annotate="on")
</textarea>
<p><b>Legacy Configuration Directives</b>:</p>
<ul>
<li><b>$InputUnixListenSocketIgnoreMsgTimestamp</b> [<b>on</b>/off]
<br>equivalent to: IgnoreTimestamp.</li>
<li><b>$InputUnixListenSocketFlowControl</b> [on/<b>off</b>] - equivalent to: FlowControl .</li>
<li><b>$IMUXSockRateLimitInterval</b> [number] - equivalent to: RateLimit.Interval
</li>
<li><b>$IMUXSockRateLimitBurst</b> [number] - equivalent to: RateLimit.Burst
</li>
<li><b>$IMUXSockRateLimitSeverity</b> [numerical severity] - equivalent to: RateLimit.Severity
</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>] - equivalent to: UsePIDFromSystem.
<br>This option was introduced in 5.7.0.</li>
<li><b>$InputUnixListenSocketUseSysTimeStamp</b> [<b>on</b>/off] equivalent to: UseSysTimeStamp .<br>
<li><b>$SystemLogSocketIgnoreMsgTimestamp</b> [<b>on</b>/off]<br>
equivalent to: SysSock.IgnoreTimestamp.</li>
<li><b>$OmitLocalLogging</b> (imuxsock) [on/<b>off</b>] equivalent to: SysSock.Use</li>
<li><b>$SystemLogSocketName</b> <name-of-socket> equivalent to: SysSock.Name</li>
<li><b>$SystemLogFlowControl</b> [on/<b>off</b>] - equivalent to: SysSock.FlowControl.</li>
<li><b>$SystemLogUsePIDFromSystem</b> [on/<b>off</b>] - equivalent to: SysSock.UsePIDFromSystem.
<br>This option was introduced in 5.7.0.</li>
<li><b>$SystemLogRateLimitInterval</b> [number] - equivalent to: SysSock.RateLimit.Interval.
</li>
<li><b>$SystemLogRateLimitBurst</b> [number] - equivalent to: SysSock.RateLimit.Burst
</li>
<li><b>$SystemLogRateLimitSeverity</b> [numerical severity] - equivalent to: SysSock.RateLimit.Severity
</li>
<li><b>$SystemLogUseSysTimeStamp</b> [<b>on</b>/off] equivalent to: SysSock.UseSysTimeStamp.
<li><b>$InputUnixListenSocketCreatePath</b> [on/<b>off</b>] - equivalent to: CreatePath
<br>[available since 4.7.0 and 5.3.0]</li>
<li><b>$AddUnixListenSocket</b> <name-of-socket> equivalent to: Socket </li>
<li><b>$InputUnixListenSocketHostName</b> <hostname> equivalent to: HostName.</li>
<li><b>$InputUnixListenSocketAnnotate</b> <on/<b>off</b>> equivalent to: Annotate.</li>
<li><b>$SystemLogSocketAnnotate</b> <on/<b>off</b>> equivalent to: SysSock.Annotate.</li>
<li><b>$SystemLogSocketParseTrusted</b> <on/<b>off</b>> equivalent to: SysSock.ParseTrusted.</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
$InputUnixListenSocket /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-2013 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>
|
