« back to all changes in this revision
Viewing changes to doc/rsyslog_conf.html
- browse files at revision 16
- compare with another revision
- download diff
- download tarball
- view history from revision 16
- Committer: Bazaar Package Importer
- Author(s): Michael Biebl
- Date: 2009-06-23 12:12:43 UTC
- mfrom: (1.1.11 upstream) (3.2.8 sid)
- Revision ID: james.westby@ubuntu.com-20090623121243-d2fejarzidywnn17
Tags: 4.2.0-1
* New upstream release of the now stable v4 branch.
- Fix warnings when /etc/rsyslog.d/ is empty. Closes: #530228
* debian/patches/imudp_multiple_udp_sockets.patch
- Removed, merged upstream.
* debian/rsyslog.default
- Set default compat mode to '4'.
* debian/rsyslog.logcheck.ignore.server
- Update logcheck rules files to also ignore rsyslogd and imklog stop
messages.
* debian/control
- Bump Standards-Version to 3.8.2. No further changes.
- Fix warnings when /etc/rsyslog.d/ is empty. Closes: #530228
* debian/patches/imudp_multiple_udp_sockets.patch
- Removed, merged upstream.
* debian/rsyslog.default
- Set default compat mode to '4'.
* debian/rsyslog.logcheck.ignore.server
- Update logcheck rules files to also ignore rsyslogd and imklog stop
messages.
* debian/control
- Bump Standards-Version to 3.8.2. No further changes.
- files added:
- doc/droppriv.html
- plugins/omstdout
- plugins/omtemplate
- tests/testsuites
- files removed:
- debian/patches/imudp_multiple_udp_sockets.patch
- files modified:
- ChangeLog
added
removed
doc/rsyslog_conf.html
20
20
features</a> require a different config file syntax, rsyslogd
21
21
should be able to work with a standard syslog.conf file. This is
22
22
especially useful while you are migrating from syslogd to rsyslogd.</p>
23
<h2>Modules</h2>
24
<p>Rsyslog has a modular design. Consequently, there is a growing
25
number of modules. Here is the entry point to their documentation and
26
what they do (list is currently not complete)</p>
27
<ul>
28
<li><a href="omsnmp.html">omsnmp</a> - SNMP
29
trap output module</li>
30
<li><a href="omrelp.html">omrelp</a> - RELP
31
output module</li>
32
<li>omgssapi - output module for GSS-enabled syslog</li>
33
<li><a href="ommysql.html">ommysql</a> - output module for MySQL</li>
34
<li>ompgsql - output module for PostgreSQL</li>
35
<li><a href="omlibdbi.html">omlibdbi</a> -
36
generic database output module (Firebird/Interbase, MS SQL, Sybase,
37
SQLLite, Ingres, Oracle, mSQL)</li>
38
<li><a href="ommail.html">ommail</a> -
39
permits rsyslog to alert folks by mail if something important happens</li>
40
<li><a href="imfile.html">imfile</a>
41
- input module for text files</li>
42
<li><a href="imrelp.html">imrelp</a> - RELP
43
input module</li>
44
<li>imudp - udp syslog message input</li>
45
<li><a href="imtcp.html">imtcp</a> - input
46
plugin for plain tcp syslog</li>
47
<li><a href="imgssapi.html">imgssapi</a> -
48
input plugin for plain tcp and GSS-enabled syslog</li>
49
<li>immark - support for mark messages</li>
50
<li><a href="imklog.html">imklog</a> - kernel logging</li>
51
<li><a href="imuxsock.html">imuxsock</a> -
52
unix sockets, including the system log socket</li>
53
<li><a href="im3195.html">im3195</a> -
54
accepts syslog messages via RFC 3195</li>
55
</ul>
56
<p>Please note that each module provides configuration
57
directives, which are NOT necessarily being listed below. Also
58
remember, that a modules configuration directive (and functionality) is
59
only available if it has been loaded (using $ModLoad).</p>
23
<h2><a href="rsyslog_conf_modules.html">Modules</a></h2>
60
24
<h2>Lines</h2>
61
25
Lines can be continued by specifying a backslash ("\") as the last
62
character of the line.<br>
63
<h2>Global Directives</h2>
64
<p>All global directives need to be specified on a line by their
65
own and must start with a dollar-sign. Here is a list in alphabetical
66
order. Follow links for a description.</p>
67
<p>Not all directives have an in-depth description right now.
68
Default values for them are in bold. A more in-depth description will
69
appear as implementation progresses. Directives may change during that
70
process, we will NOT try hard to maintain backwards compatibility
71
(after all, v3 is still very early in development and quite
72
unstable...). So you have been warned ;)</p>
73
<p><b>Be sure to read information about <a href="queues.html">queues in rsyslog</a></b> -
74
many parameter settings modify queue parameters. If in doubt, use the
75
default, it is usually well-chosen and applicable in most cases.</p>
76
<ul>
77
<li><a href="rsconf1_actionexeconlywhenpreviousissuspended.html">$ActionExecOnlyWhenPreviousIsSuspended</a></li>
78
<li>$ActionExecOnlyOnceEveryInterval <seconds> -
79
execute action only if the last execute is at last
80
<seconds> seconds in the past (more info in <a href="ommail.html">ommail</a>,
81
but may be used with any action)</li>
82
<li><i><b>$ActionExecOnlyEveryNthTime</b> <number></i> - If configured, the next action will
83
only be executed every n-th time. For example, if configured to 3, the first two messages
84
that go into the action will be dropped, the 3rd will actually cause the action to execute,
85
the 4th and 5th will be dropped, the 6th executed under the action, ... and so on. Note:
86
this setting is automatically re-set when the actual action is defined.</li>
87
<li><i><b>$ActionExecOnlyEveryNthTimeTimeout</b> <number-of-seconds></i> - has a meaning only if
88
$ActionExecOnlyEveryNthTime is also configured for the same action. If so, the timeout
89
setting specifies after which period the counting of "previous actions" expires and
90
a new action count is begun. Specify 0 (the default) to disable timeouts.
91
<br>
92
<i>Why is this option needed?</i> Consider this case: a message comes in at, eg., 10am. That's
93
count 1. Then, nothing happens for the next 10 hours. At 8pm, the next
94
one occurs. That's count 2. Another 5 hours later, the next message
95
occurs, bringing the total count to 3. Thus, this message now triggers
96
the rule.
97
<br>
98
The question is if this is desired behavior? Or should the rule only be
99
triggered if the messages occur within an e.g. 20 minute window? If the
100
later is the case, you need a
101
<br>
102
$ActionExecOnlyEveryNthTimeTimeout 1200
103
<br>
104
This directive will timeout previous messages seen if they are older
105
than 20 minutes. In the example above, the count would now be always 1
106
and consequently no rule would ever be triggered.
107
108
<li>$ActionFileDefaultTemplate [templateName] - sets a new default template for file actions</li>
109
<li>$ActionFileEnableSync [on/<span style="font-weight: bold;">off</span>] - enables file
110
syncing capability of omfile</li>
111
<li>$ActionForwardDefaultTemplate [templateName] - sets a new
112
default template for UDP and plain TCP forwarding action</li>
113
<li>$ActionGSSForwardDefaultTemplate [templateName] - sets a
114
new default template for GSS-API forwarding action</li>
115
<li>$ActionQueueCheckpointInterval <number></li>
116
<li>$ActionQueueDequeueSlowdown <number> [number
117
is timeout in <i> micro</i>seconds (1000000us is 1sec!),
118
default 0 (no delay). Simple rate-limiting!]</li>
119
<li>$ActionQueueDiscardMark <number> [default
120
9750]</li>
121
<li>$ActionQueueDiscardSeverity <number>
122
[*numerical* severity! default 4 (warning)]</li>
123
<li>$ActionQueueFileName <name></li>
124
<li>$ActionQueueHighWaterMark <number> [default
125
8000]</li>
126
<li>$ActionQueueImmediateShutdown [on/<b>off</b>]</li>
127
<li>$ActionQueueSize <number></li>
128
<li>$ActionQueueLowWaterMark <number> [default
129
2000]</li>
130
<li>$ActionQueueMaxFileSize <size_nbr>, default 1m</li>
131
<li>$ActionQueueTimeoutActionCompletion <number>
132
[number is timeout in ms (1000ms is 1sec!), default 1000, 0 means
133
immediate!]</li>
134
<li>$ActionQueueTimeoutEnqueue <number> [number
135
is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]</li>
136
<li>$ActionQueueTimeoutShutdown <number> [number
137
is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]</li>
138
<li>$ActionQueueWorkerTimeoutThreadShutdown
139
<number> [number is timeout in ms (1000ms is 1sec!),
140
default 60000 (1 minute)]</li>
141
<li>$ActionQueueType [FixedArray/LinkedList/<b>Direct</b>/Disk]</li>
142
<li>$ActionQueueSaveOnShutdown [on/<b>off</b>]
143
</li>
144
<li>$ActionQueueWorkerThreads <number>, num worker threads, default 1, recommended 1</li>
145
<li>$ActionQueueWorkerThreadMinumumMessages <number>, default 100</li>
146
<li><a href="rsconf1_actionresumeinterval.html">$ActionResumeInterval</a></li>
147
<li>$ActionResumeRetryCount <number> [default 0, -1 means eternal]</li>
148
<li>$ActionSendResendLastMsgOnReconn <[on/<b>off</b>]> specifies if the last message is to be resend when a connecition broken and has been reconnedcted. May increase reliability, but comes at the risk of message duplication.
149
<li>$ActionSendStreamDriver <driver basename> just like $DefaultNetstreamDriver, but for the specific action
150
</li><li>$ActionSendStreamDriverMode <mode>, default 0, mode to use with the stream driver
151
(driver-specific)</li><li>$ActionSendStreamDriverAuthMode <mode>, authentication mode to use with the stream driver
152
(driver-specific)</li><li>$ActionSendStreamDriverPermittedPeer <ID>, accepted fingerprint (SHA1) or name of remote peer
153
(driver-specific) -<span style="font-weight: bold;"> directive may go away</span>!</li>
154
<li><a href="rsconf1_allowedsender.html">$AllowedSender</a></li>
155
<li><a href="rsconf1_controlcharacterescapeprefix.html">$ControlCharacterEscapePrefix</a></li>
156
<li><a href="rsconf1_debugprintcfsyslinehandlerlist.html">$DebugPrintCFSyslineHandlerList</a></li>
157
158
<li><a href="rsconf1_debugprintmodulelist.html">$DebugPrintModuleList</a></li>
159
<li><a href="rsconf1_debugprinttemplatelist.html">$DebugPrintTemplateList</a></li>
160
<li>$DefaultNetstreamDriver <drivername>, the default <a href="netstream.html">network stream driver</a> to use. Defaults to ptcp.$DefaultNetstreamDriverCAFile </path/to/cafile.pem></li>
161
<li>$DefaultNetstreamDriverCertFile </path/to/certfile.pem></li>
162
<li>$DefaultNetstreamDriverKeyFile </path/to/keyfile.pem></li>
163
<li><a href="rsconf1_dircreatemode.html">$DirCreateMode</a></li>
164
<li><a href="rsconf1_dirgroup.html">$DirGroup</a></li>
165
<li><a href="rsconf1_dirowner.html">$DirOwner</a></li>
166
<li><a href="rsconf1_dropmsgswithmaliciousdnsptrrecords.html">$DropMsgsWithMaliciousDnsPTRRecords</a></li>
167
<li><a href="rsconf1_droptrailinglfonreception.html">$DropTrailingLFOnReception</a></li>
168
<li><a href="rsconf1_dynafilecachesize.html">$DynaFileCacheSize</a></li>
169
<li><a href="rsconf1_escapecontrolcharactersonreceive.html">$EscapeControlCharactersOnReceive</a></li>
170
<li>$ErrorMessagesToStderr [<b>on</b>|off] - direct rsyslogd error message to stderr (in addition to other targets)</li>
171
<li><a href="rsconf1_failonchownfailure.html">$FailOnChownFailure</a></li>
172
<li><a href="rsconf1_filecreatemode.html">$FileCreateMode</a></li>
173
<li><a href="rsconf1_filegroup.html">$FileGroup</a></li>
174
<li><a href="rsconf1_fileowner.html">$FileOwner</a></li>
175
<li><a href="rsconf1_gssforwardservicename.html">$GssForwardServiceName</a></li>
176
<li><a href="rsconf1_gsslistenservicename.html">$GssListenServiceName</a></li>
177
<li><a href="rsconf1_gssmode.html">$GssMode</a></li>
178
<li><a href="rsconf1_includeconfig.html">$IncludeConfig</a></li><li>MainMsgQueueCheckpointInterval <number></li>
179
<li>$MainMsgQueueDequeueSlowdown <number> [number
180
is timeout in <i> micro</i>seconds (1000000us is 1sec!),
181
default 0 (no delay). Simple rate-limiting!]</li>
182
<li>$MainMsgQueueDiscardMark <number> [default
183
9750]</li>
184
<li>$MainMsgQueueDiscardSeverity <severity>
185
[either a textual or numerical severity! default 4 (warning)]</li>
186
<li>$MainMsgQueueFileName <name></li>
187
<li>$MainMsgQueueHighWaterMark <number> [default
188
8000]</li>
189
<li>$MainMsgQueueImmediateShutdown [on/<b>off</b>]</li>
190
<li><a href="rsconf1_mainmsgqueuesize.html">$MainMsgQueueSize</a></li>
191
<li>$MainMsgQueueLowWaterMark <number> [default
192
2000]</li>
193
<li>$MainMsgQueueMaxFileSize <size_nbr>, default
194
1m</li>
195
<li>$MainMsgQueueTimeoutActionCompletion
196
<number> [number is timeout in ms (1000ms is 1sec!),
197
default
198
1000, 0 means immediate!]</li>
199
<li>$MainMsgQueueTimeoutEnqueue <number> [number
200
is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]</li>
201
<li>$MainMsgQueueTimeoutShutdown <number> [number
202
is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]</li>
203
<li>$MainMsgQueueWorkerTimeoutThreadShutdown
204
<number> [number is timeout in ms (1000ms is 1sec!),
205
default 60000 (1 minute)]</li>
206
<li>$MainMsgQueueType [<b>FixedArray</b>/LinkedList/Direct/Disk]</li>
207
<li>$MainMsgQueueSaveOnShutdown [on/<b>off</b>]
208
</li>
209
<li>$MainMsgQueueWorkerThreads <number>, num
210
worker threads, default 1, recommended 1</li>
211
<li>$MainMsgQueueWorkerThreadMinumumMessages <number>, default 100</li>
212
<li><a href="rsconf1_markmessageperiod.html">$MarkMessagePeriod</a> (immark)</li>
213
<li><b><i>$MaxMessageSize</i></b> <size_nbr>, default 2k - allows to specify maximum supported message size
214
(both for sending and receiving). The default
215
should be sufficient for almost all cases. Do not set this below 1k, as it would cause
216
interoperability problems with other syslog implementations.<br>
217
Change the setting to e.g. 32768 if you would like to
218
support large message sizes for IHE (32k is the current maximum
219
needed for IHE). I was initially tempted to set the default to 32k,
220
but there is a some memory footprint with the current
221
implementation in rsyslog.
222
<br>If you intend to receive Windows Event Log data (e.g. via
223
<a href="http://www.eventreporter.com/">EventReporter</a>), you might want to
224
increase this number to an even higher value, as event
225
log messages can be very lengthy ("$MaxMessageSize 64k" is not a bad idea).
226
Note: testing showed that 4k seems to be
227
the typical maximum for <b>UDP</b> based syslog. This is an IP stack
228
restriction. Not always ... but very often. If you go beyond
229
that value, be sure to test that rsyslogd actually does what
230
you think it should do ;) It is highly suggested to use a TCP based transport
231
instead of UDP (plain TCP syslog, RELP). This resolves the UDP stack size restrictions.
232
<br>Note that 2k, the current default, is the smallest size that must be
233
supported in order to be compliant to the upcoming new syslog RFC series.
234
</li>
235
<li><a href="rsconf1_moddir.html">$ModDir</a></li>
236
<li><a href="rsconf1_modload.html">$ModLoad</a></li>
237
<li><a href="rsconf1_repeatedmsgreduction.html">$RepeatedMsgReduction</a></li>
238
<li><a href="rsconf1_resetconfigvariables.html">$ResetConfigVariables</a></li>
239
<li>$WorkDirectory <name> (directory for spool
240
and other work files)</li>
241
<li>$UDPServerAddress <IP> (imudp) -- local IP
242
address (or name) the UDP listens should bind to</li>
243
<li>$UDPServerRun <port> (imudp) -- former
244
-r<port> option, default 514, start UDP server on this
245
port, "*" means all addresses</li>
246
<li><a href="rsconf1_umask.html">$UMASK</a></li>
247
</ul>
248
<p><b>Where <size_nbr> is specified above,</b>
249
modifiers can be used after the number part. For example, 1k means
250
1024. Supported are k(ilo), m(ega), g(iga), t(era), p(eta) and e(xa).
251
Lower case letters refer to the traditional binary defintion (e.g. 1m
252
equals 1,048,576) whereas upper case letters refer to their new
253
1000-based definition (e.g 1M equals 1,000,000).</p>
254
<p>Numbers may include '.' and ',' for readability. So you can
255
for example specify either "1000" or "1,000" with the same result.
256
Please note that rsyslogd simply ignores the punctuation. Form it's
257
point of view, "1,,0.0.,.,0" also has the value 1000. </p>
26
character of the line. There is a hard-coded maximum line length of 4K.
27
If you need lines larger than that, you need to change compile-time
28
settings inside rsyslog and recompile.
29
<h2><a href="rsyslog_conf_global.html">Global Directives</a></h2>
258
30
<h2>Basic Structure</h2>
259
31
<p>Rsyslog supports standard sysklogd's configuration file format
260
32
and extends it. So in general, you can take a "normal" syslog.conf and
273
45
<br>
274
46
Lines starting with a hash mark ("#'') and empty lines are ignored.
275
47
</p>
276
<h2>Templates</h2>
277
<p>Templates are a key feature of rsyslog. They allow to specify
278
any
279
format a user might want. They are also used for dynamic file name
280
generation. Every output in rsyslog uses templates - this holds true
281
for files, user messages and so on.
282
Please note that there is an
283
<a href="http://www.rsyslog.com/Article354.phtml">online tutorial on rsyslog templates</a>
284
available on the web. We recommend viewing it.
285
The database writer expects its
286
template to be a proper SQL statement - so this is highly customizable
287
too. You might ask how does all of this work when no templates at all
288
are specified. Good question ;) The answer is simple, though. Templates
289
compatible with the stock syslogd formats are hardcoded into rsyslogd.
290
So if no template is specified, we use one of these hardcoded
291
templates. Search for "template_" in syslogd.c and you will find the
292
hardcoded ones.</p>
293
<p>A template consists of a template directive, a name, the
294
actual template text and optional options. A sample is:</p>
295
<blockquote><code>$template MyTemplateName,"\7Text
296
%property% some more text\n",<options></code></blockquote>
297
<p>The "$template" is the template directive. It tells rsyslog
298
that this line contains a template. "MyTemplateName" is the template
299
name. All
300
other config lines refer to this name. The text within quotes is the
301
actual template text. The backslash is an escape character, much as it
302
is in C. It does all these "cool" things. For example, \7 rings the
303
bell (this is an ASCII value), \n is a new line. C programmers and perl
304
coders have the advantage of knowing this, but the set in rsyslog is a
305
bit restricted currently.
306
</p>
307
<p>All text in the template is used literally, except for things
308
within percent signs. These are properties and allow you access to the
309
contents of the syslog message. Properties are accessed via the
310
property replacer (nice name, huh) and it can do cool things, too. For
311
example, it can pick a substring or do date-specific formatting. More
312
on this is below, on some lines of the property replacer.<br>
313
<br>
314
The <options> part is optional. It carries options
315
influencing the template as whole. See details below. Be sure NOT to
316
mistake template options with property options - the later ones are
317
processed by the property replacer and apply to a SINGLE property, only
318
(and not the whole template).<br>
319
<br>
320
Template options are case-insensitive. Currently defined are: </p>
321
<p><b>sql</b> - format the string suitable for a SQL
322
statement in MySQL format. This will replace single quotes ("'") and
323
the backslash character by their backslash-escaped counterpart ("\'"
324
and "\\") inside each field. Please note that in MySQL configuration,
325
the <code class="literal">NO_BACKSLASH_ESCAPES</code>
326
mode must be turned off for this format to work (this is the default).</p>
327
<p><b>stdsql</b> - format the string suitable for a
328
SQL statement that is to be sent to a standards-compliant sql server.
329
This will replace single quotes ("'") by two single quotes ("''")
330
inside each field. You must use stdsql together with MySQL if in MySQL
331
configuration the
332
<code class="literal">NO_BACKSLASH_ESCAPES</code> is
333
turned on.</p>
334
<p>Either the <b>sql</b> or <b>stdsql</b>
335
option <b>must</b> be specified when a template is used
336
for writing to a database, otherwise injection might occur. Please note
337
that due to the unfortunate fact that several vendors have violated the
338
sql standard and introduced their own escape methods, it is impossible
339
to have a single option doing all the work. So you yourself
340
must make sure you are using the right format. <b>If you choose
341
the wrong one, you are still vulnerable to sql injection.</b><br>
342
<br>
343
Please note that the database writer *checks* that the sql option is
344
present in the template. If it is not present, the write database
345
action is disabled. This is to guard you against accidental forgetting
346
it and then becoming vulnerable to SQL injection. The sql option can
347
also be useful with files - especially if you want to import them into
348
a database on another machine for performance reasons. However, do NOT
349
use it if you do not have a real need for it - among others, it takes
350
some toll on the processing time. Not much, but on a really busy system
351
you might notice it ;)</p>
352
<p>The default template for the write to database action has the
353
sql option set. As we currently support only MySQL and the sql option
354
matches the default MySQL configuration, this is a good choice.
355
However, if you have turned on
356
<code class="literal">NO_BACKSLASH_ESCAPES</code> in
357
your MySQL config, you need to supply a template with the stdsql
358
option. Otherwise you will become vulnerable to SQL injection. <br>
359
<br>
360
To escape:<br>
361
% = \%<br>
362
\ = \\ --> '\' is used to escape (as in C)<br>
363
$template TraditionalFormat,%timegenerated% %HOSTNAME%
364
%syslogtag%%msg%\n"<br>
365
<br>
366
Properties can be accessed by the <a href="property_replacer.html">property
367
replacer</a> (see there for details).</p>
368
<p><b>Please note that templates can also by
369
used to generate selector lines with dynamic file names.</b> For
370
example, if you would like to split syslog messages from different
371
hosts to different files (one per host), you can define the following
372
template:</p>
373
<blockquote><code>$template
374
DynFile,"/var/log/system-%HOSTNAME%.log"</code></blockquote>
375
<p>This template can then be used when defining an output
376
selector line. It will result in something like
377
"/var/log/system-localhost.log"</p>
378
<p>Template
379
names beginning with "RSYSLOG_" are reserved for rsyslog use. Do NOT
380
use them if, otherwise you may receive a conflict in the future (and
381
quite unpredictable behaviour). There is a small set of pre-defined
382
templates that you can use without the need to define it:</p>
383
<ul>
384
<li><span style="font-weight: bold;">RSYSLOG_TraditionalFileFormat</span>
385
- the "old style" default log file format with low-precision timestamps</li>
386
<li><span style="font-weight: bold;">RSYSLOG_FileFormat</span>
387
- a modern-style logfile format similar to TraditionalFileFormat, buth
388
with high-precision timestamps and timezone information</li>
389
<li><span style="font-weight: bold;">RSYSLOG_TraditionalForwardFormat</span>
390
- the traditional forwarding format with low-precision timestamps. Most
391
useful if you send messages to other syslogd's or rsyslogd
392
below
393
version 3.12.5.</li>
394
<li><span style="font-weight: bold;">RSYSLOG_ForwardFormat</span>
395
- a new high-precision forwarding format very similar to the
396
traditional one, but with high-precision timestamps and timezone
397
information. Recommended to be used when sending messages to rsyslog
398
3.12.5 or above.</li>
399
<li><span style="font-weight: bold;">RSYSLOG_SyslogProtocol23Format</span>
400
- the format specified in IETF's internet-draft
401
ietf-syslog-protocol-23, which is assumed to be come the new syslog
402
standard RFC. This format includes several improvements. The rsyslog
403
message parser understands this format, so you can use it together with
404
all relatively recent versions of rsyslog. Other syslogd's may get
405
hopelessly confused if receiving that format, so check before you use
406
it. Note that the format is unlikely to change when the final RFC comes
407
out, but this may happen.</li>
408
<li><span style="font-weight: bold;">RSYSLOG_DebugFormat</span>
409
- a special format used for troubleshooting property problems. This format
410
is meant to be written to a log file. Do <b>not</b> use for production or remote
411
forwarding.</li>
412
</ul>
413
<h2>Output Channels</h2>
414
<p>Output Channels are a new concept first introduced in rsyslog
415
0.9.0. <b>As of this writing, it is most likely that they will
416
be replaced by something different in the future.</b> So if you
417
use them, be prepared to change you configuration file syntax when you
418
upgrade to a later release.<br>
419
<br>
420
The idea behind output channel definitions is that it shall provide an
421
umbrella for any type of output that the user might want. In essence,<br>
422
this is the "file" part of selector lines (and this is why we are not
423
sure output channel syntax will stay after the next review). There is a<br>
424
difference, though: selector channels both have filter conditions
425
(currently facility and severity) as well as the output destination.
426
Output channels define the output definition, only. As of this build,
427
they can only be used to write to files - not pipes, ttys or whatever
428
else. If we stick with output channels, this will change over time.</p>
429
<p>In concept, an output channel includes everything needed to
430
know about an output actions. In practice, the current implementation
431
only carries<br>
432
a filename, a maximum file size and a command to be issued when this
433
file size is reached. More things might be present in future version,
434
which might also change the syntax of the directive.</p>
435
<p>Output channels are defined via an $outchannel directive. It's
436
syntax is as follows:<br>
437
<br>
438
$outchannel name,file-name,max-size,action-on-max-size<br>
439
<br>
440
name is the name of the output channel (not the file), file-name is the
441
file name to be written to, max-size the maximum allowed size and
442
action-on-max-size a command to be issued when the max size is reached.
443
This command always has exactly one parameter. The binary is that part
444
of action-on-max-size before the first space, its parameter is
445
everything behind that space.<br>
446
<br>
447
Please note that max-size is queried BEFORE writing the log message to
448
the file. So be sure to set this limit reasonably low so that any
449
message might fit. For the current release, setting it 1k lower than
450
you expected is helpful. The max-size must always be specified in bytes
451
- there are no special symbols (like 1k, 1m,...) at this point of
452
development.<br>
453
<br>
454
Keep in mind that $outchannel just defines a channel with "name". It
455
does not activate it. To do so, you must use a selector line (see
456
below). That selector line includes the channel name plus an $ sign in
457
front of it. A sample might be:<br>
458
<br>
459
*.* $mychannel<br>
460
<br>
461
In its current form, output channels primarily provide the ability to
462
size-limit an output file. To do so, specify a maximum size. When this
463
size is reached, rsyslogd will execute the action-on-max-size command
464
and then reopen the file and retry. The command should be something
465
like a <a href="log_rotation_fix_size.html">log rotation
466
script</a> or a similar thing.</p>
467
<p>If there is no action-on-max-size command or the command did
468
not resolve the situation, the file is closed and never reopened by
469
rsyslogd (except, of course, by huping it). This logic was integrated
470
when we first experienced severe issues with files larger 2gb, which
471
could lead to rsyslogd dumping core. In such cases, it is more
472
appropriate to stop writing to a single file. Meanwhile, rsyslogd has
473
been fixed to support files larger 2gb, but obviously only on file
474
systems and operating system versions that do so. So it can still make
475
sense to enforce a 2gb file size limit.</p>
476
<h2>Filter Conditions</h2>
477
<p>Rsyslog offers four different types "filter conditions":</p>
478
<ul>
479
<li>BSD-style blocks</li>
480
<li>"traditional" severity and facility based selectors</li>
481
<li>property-based filters</li>
482
<li>expression-based filters</li>
483
</ul>
484
<h3>Blocks</h3>
485
<p>Rsyslogd supports BSD-style blocks inside rsyslog.conf. Each
486
block of lines is separated from the previous block by a program or
487
hostname specification. A block will only log messages corresponding to
488
the most recent program and hostname specifications given. Thus, a
489
block which selects ‘ppp’ as the program, directly followed by a block
490
that selects messages from the hostname ‘dialhost’, then the second
491
block will only log messages from the ppp program on dialhost.
492
</p>
493
<p>A program specification is a line beginning with ‘!prog’ and
494
the following blocks will be associated with calls to syslog from that
495
specific program. A program specification for ‘foo’ will also match any
496
message logged by the kernel with the prefix ‘foo: ’. Alternatively, a
497
program specification ‘-foo’ causes the following blocks to be applied
498
to messages from any program but the one specified. A hostname
499
specification of the form ‘+hostname’ and the following blocks will be
500
applied to messages received from the specified hostname.
501
Alternatively, a hostname specification ‘-hostname’ causes the
502
following blocks to be applied to messages from any host but the one
503
specified. If the hostname is given as ‘@’, the local hostname will be
504
used. (NOT YET IMPLEMENTED) A program or hostname specification may be
505
reset by giving the program or hostname as ‘*’.</p>
506
<p>Please note that the "#!prog", "#+hostname" and "#-hostname"
507
syntax available in BSD syslogd is not supported by rsyslogd. By
508
default, no hostname or program is set.</p>
509
<h3>Selectors</h3>
510
<p><b>Selectors are the traditional way of filtering syslog
511
messages.</b> They have been kept in rsyslog with their original
512
syntax, because it is well-known, highly effective and also needed for
513
compatibility with stock syslogd configuration files. If you just need
514
to filter based on priority and facility, you should do this with
515
selector lines. They are <b>not</b> second-class citizens
516
in rsyslog and offer the best performance for this job.</p>
517
<p>The selector field itself again consists of two parts, a
518
facility and a priority, separated by a period (".''). Both parts are
519
case insensitive and can also be specified as decimal numbers, but
520
don't do that, you have been warned. Both facilities and priorities are
521
described in rsyslog(3). The names mentioned below correspond to the
522
similar LOG_-values in /usr/include/rsyslog.h.<br>
523
<br>
524
The facility is one of the following keywords: auth, authpriv, cron,
525
daemon, kern, lpr, mail, mark, news, security (same as auth), syslog,
526
user, uucp and local0 through local7. The keyword security should not
527
be used anymore and mark is only for internal use and therefore should
528
not be used in applications. Anyway, you may want to specify and
529
redirect these messages here. The facility specifies the subsystem that
530
produced the message, i.e. all mail programs log with the mail facility
531
(LOG_MAIL) if they log using syslog.<br>
532
<br>
533
The priority is one of the following keywords, in ascending order:
534
debug, info, notice, warning, warn (same as warning), err, error (same
535
as err), crit, alert, emerg, panic (same as emerg). The keywords error,
536
warn and panic are deprecated and should not be used anymore. The
537
priority defines the severity of the message.<br>
538
<br>
539
The behavior of the original BSD syslogd is that all messages of the
540
specified priority and higher are logged according to the given action.
541
Rsyslogd behaves the same, but has some extensions.<br>
542
<br>
543
In addition to the above mentioned names the rsyslogd(8) understands
544
the following extensions: An asterisk ("*'') stands for all facilities
545
or all priorities, depending on where it is used (before or after the
546
period). The keyword none stands for no priority of the given facility.<br>
547
<br>
548
You can specify multiple facilities with the same priority pattern in
549
one statement using the comma (",'') operator. You may specify as much
550
facilities as you want. Remember that only the facility part from such
551
a statement is taken, a priority part would be skipped.</p>
552
<p>Multiple selectors may be specified for a single action using
553
the semicolon (";'') separator. Remember that each selector in the
554
selector field is capable to overwrite the preceding ones. Using this
555
behavior you can exclude some priorities from the pattern.</p>
556
<p>Rsyslogd has a syntax extension to the original BSD source,
557
that makes its use more intuitively. You may precede every priority
558
with an equation sign ("='') to specify only this single priority and
559
not any of the above. You may also (both is valid, too) precede the
560
priority with an exclamation mark ("!'') to ignore all that
561
priorities, either exact this one or this and any higher priority. If
562
you use both extensions than the exclamation mark must occur before the
563
equation sign, just use it intuitively.</p>
564
<h3>Property-Based Filters</h3>
565
<p>Property-based filters are unique to rsyslogd. They allow to
566
filter on any property, like HOSTNAME, syslogtag and msg. A list of all
567
currently-supported properties can be found in the <a href="property_replacer.html">property replacer documentation</a>
568
(but keep in mind that only the properties, not the replacer is
569
supported). With this filter, each properties can be checked against a
570
specified value, using a specified compare operation.</p>
571
<p>A property-based filter must start with a colon in column 0.
572
This tells rsyslogd that it is the new filter type. The colon must be
573
followed by the property name, a comma, the name of the compare
574
operation to carry out, another comma and then the value to compare
575
against. This value must be quoted. There can be spaces and tabs
576
between the commas. Property names and compare operations are
577
case-sensitive, so "msg" works, while "MSG" is an invalid property
578
name. In brief, the syntax is as follows:</p>
579
<p><code><b>:property, [!]compare-operation, "value"</b></code></p>
580
<p>The following <b>compare-operations</b> are
581
currently supported:</p>
582
<table id="table1" border="1" width="100%">
583
<tbody>
584
<tr>
585
<td>contains</td>
586
<td>Checks if the string provided in value is contained in
587
the property. There must be an exact match, wildcards are not supported.</td>
588
</tr>
589
<tr>
590
<td>isequal</td>
591
<td>Compares the "value" string provided and the property
592
contents. These two values must be exactly equal to match. The
593
difference to contains is that contains searches for the value anywhere
594
inside the property value, whereas all characters must be identical for
595
isequal. As such, isequal is most useful for fields like syslogtag or
596
FROMHOST, where you probably know the exact contents.</td>
597
</tr>
598
<tr>
599
<td>startswith</td>
600
<td>Checks if the value is found exactly at the beginning
601
of the property value. For example, if you search for "val" with
602
<p><code><b>:msg, startswith, "val"</b></code></p>
603
<p>it will be a match if msg contains "values are in this
604
message" but it won't match if the msg contains "There are values in
605
this message" (in the later case, contains would match). Please note
606
that "startswith" is by far faster than regular expressions. So even
607
once they are implemented, it can make very much sense
608
(performance-wise) to use "startswith".</p>
609
</td>
610
</tr>
611
<tr>
612
<td>regex</td>
613
<td>Compares the property against the provided POSIX
614
regular
615
expression.</td>
616
</tr>
617
</tbody>
618
</table>
619
<p>You can use the bang-character (!) immediately in front of a
620
compare-operation, the outcome of this operation is negated. For
621
example, if msg contains "This is an informative message", the
622
following sample would not match:</p>
623
<p><code><b>:msg, contains, "error"</b></code></p>
624
<p>but this one matches:</p>
625
<p><code><b>:msg, !contains, "error"</b></code></p>
626
<p>Using negation can be useful if you would like to do some
627
generic processing but exclude some specific events. You can use the
628
discard action in conjunction with that. A sample would be:</p>
629
<p><code><b>*.*
630
/var/log/allmsgs-including-informational.log<br>
631
:msg, contains, "informational" <font color="#ff0000" size="4">~</font>
632
<br>
633
*.* /var/log/allmsgs-but-informational.log</b></code></p>
634
<p>Do not overlook the red tilde in line 2! In this sample, all
635
messages are written to the file allmsgs-including-informational.log.
636
Then, all messages containing the string "informational" are discarded.
637
That means the config file lines below the "discard line" (number 2 in
638
our sample) will not be applied to this message. Then, all remaining
639
lines will also be written to the file allmsgs-but-informational.log.</p>
640
<p><b>Value</b> is a quoted string. It supports some
641
escape sequences:</p>
642
<p>\" - the quote character (e.g. "String with \"Quotes\"")<br>
643
\\ - the backslash character (e.g. "C:\\tmp")</p>
644
<p>Escape sequences always start with a backslash. Additional
645
escape sequences might be added in the future. Backslash characters <b>must</b>
646
be escaped. Any other sequence then those outlined above is invalid and
647
may lead to unpredictable results.</p>
648
<p>Probably, "msg" is the most prominent use case of property
649
based filters. It is the actual message text. If you would like to
650
filter based on some message content (e.g. the presence of a specific
651
code), this can be done easily by:</p>
652
<p><code><b>:msg, contains, "ID-4711"</b></code></p>
653
<p>This filter will match when the message contains the string
654
"ID-4711". Please note that the comparison is case-sensitive, so it
655
would not match if "id-4711" would be contained in the message.</p>
656
<p><code><b>:msg, regex, "fatal .* error"</b></code></p>
657
<p>This filter uses a POSIX regular expression. It matches when
658
the
659
string contains the words "fatal" and "error" with anything in between
660
(e.g. "fatal net error" and "fatal lib error" but not "fatal error" as
661
two spaces are required by the regular expression!).</p>
662
<p>Getting property-based filters right can sometimes be
663
challenging. In order to help you do it with as minimal effort as
664
possible, rsyslogd spits out debug information for all property-based
665
filters during their evaluation. To enable this, run rsyslogd in
666
foreground and specify the "-d" option.</p>
667
<p>Boolean operations inside property based filters (like
668
'message contains "ID17" or message contains "ID18"') are currently not
669
supported (except for "not" as outlined above). Please note that while
670
it is possible to query facility and severity via property-based
671
filters, it is far more advisable to use classic selectors (see above)
672
for those cases.</p>
673
<h3>Expression-Based Filters</h3>
674
Expression based filters allow
675
filtering on arbitrary complex expressions, which can include boolean,
676
arithmetic and string operations. Expression filters will evolve into a
677
full configuration scripting language. Unfortunately, their syntax will
678
slightly change during that process. So if you use them now, you need
679
to be prepared to change your configuration files some time later.
680
However, we try to implement the scripting facility as soon as possible
681
(also in respect to stage work needed). So the window of exposure is
682
probably not too long.<br>
683
<br>
684
Expression based filters are indicated by the keyword "if" in column 1
685
of a new line. They have this format:<br>
686
<br>
687
if expr then action-part-of-selector-line<br>
688
<br>
689
"If" and "then" are fixed keywords that mus be present. "expr" is a
690
(potentially quite complex) expression. So the <a href="expression.h">expression documentation</a> for
691
details. "action-part-of-selector-line" is an action, just as you know
692
it (e.g. "/var/log/logfile" to write to that file).<br>
693
<br>
694
A few quick samples:<br>
695
<br>
696
<code>
697
*.* /var/log/file1 # the traditional way<br>
698
if $msg contains 'error' /var/log/errlog # the expression-based way<br>
699
</code>
700
<br>
701
Right now, you need to specify numerical values if you would like to
702
check for facilities and severity. These can be found in <a href="http://www.ietf.org/rfc/rfc3164.txt">RFC 3164</a>.
703
If you don't like that, you can of course also use the textual property
704
- just be sure to use the right one. As expression support is enhanced,
705
this will change. For example, if you would like to filter on message
706
that have facility local0, start with "DEVNAME" and have either
707
"error1" or "error0" in their message content, you could use the
708
following filter:<br>
709
<br>
710
<code>
711
if $syslogfacility-text == 'local0' and $msg
712
startswith 'DEVNAME' and ($msg contains 'error1' or $msg contains
713
'error0') then /var/log/somelog<br>
714
</code>
715
<br>
716
Please note that the above <span style="font-weight: bold;">must
717
all be on one line</span>! And if you would like to store all
718
messages except those that contain "error1" or "error0", you just need
719
to add a "not":<br>
720
<br>
721
<code>
722
if $syslogfacility-text == 'local0' and $msg
723
startswith 'DEVNAME' and <span style="font-weight: bold;">not</span>
724
($msg contains 'error1' or $msg contains
725
'error0') then /var/log/somelog<br>
726
</code>
727
<br>
728
If you would like to do case-insensitive comparisons, use
729
"contains_i" instead of "contains" and "startswith_i" instead of
730
"startswith".<br>
731
<br>
732
Note that regular expressions are currently NOT
733
supported in expression-based filters. These will be added later when
734
function support is added to the expression engine (the reason is that
735
regular expressions will be a separate loadable module, which requires
736
some more prequisites before it can be implemented).<br>
737
<h2>ACTIONS</h2>
738
<p>The action field of a rule describes what to do with the
739
message. In general, message content is written to a kind of "logfile".
740
But also other actions might be done, like writing to a database table
741
or forwarding to another host.<br>
742
<br>
743
Templates can be used with all actions. If used, the specified template
744
is used to generate the message content (instead of the default
745
template). To specify a template, write a semicolon after the action
746
value immediately followed by the template name.<br>
747
<br>
748
Beware: templates MUST be defined BEFORE they are used. It is OK to
749
define some templates, then use them in selector lines, define more
750
templates and use use them in the following selector lines. But it is
751
NOT permitted to use a template in a selector line that is above its
752
definition. If you do this, the action will be ignored.</p>
753
<p><b>You can have multiple actions for a single selector </b> (or
754
more precisely a single filter of such a selector line). Each action
755
must be on its own line and the line must start with an ampersand
756
('&') character and have no filters. An example would be</p>
757
<p><code><b>*.=crit rger<br>
758
& root<br>
759
& /var/log/critmsgs</b></code></p>
760
<p>These three lines send critical messages to the user rger and
761
root and also store them in /var/log/critmsgs. <b>Using multiple
762
actions per selector is</b> convenient and also <b>offers
763
a performance benefit</b>. As the filter needs to be evaluated
764
only once, there is less computation required to process the directive
765
compared to the otherwise-equal config directives below:</p>
766
<p><code><b>*.=crit rger<br>
767
*.=crit root<br>
768
*.=crit /var/log/critmsgs</b></code></p>
769
<p> </p>
770
<h3>Regular File</h3>
771
<p>Typically messages are logged to real files. The file has to
772
be specified with full pathname, beginning with a slash "/''.<br>
773
<br>
774
You may prefix each entry with the minus "-'' sign to omit syncing the
775
file after every logging. Note that you might lose information if the
776
system crashes right behind a write attempt. Nevertheless this might
777
give you back some performance, especially if you run programs that use
778
logging in a very verbose manner.</p>
779
<p>If your system is connected to a reliable UPS and you receive
780
lots of log data (e.g. firewall logs), it might be a very good idea to
781
turn of
782
syncing by specifying the "-" in front of the file name. </p>
783
<p><b>The filename can be either static </b>(always
784
the same) or <b>dynamic</b> (different based on message
785
received). The later is useful if you would automatically split
786
messages into different files based on some message criteria. For
787
example, dynamic file name selectors allow you to split messages into
788
different files based on the host that sent them. With dynamic file
789
names, everything is automatic and you do not need any filters. </p>
790
<p>It works via the template system. First, you define a template
791
for the file name. An example can be seen above in the description of
792
template. We will use the "DynFile" template defined there. Dynamic
793
filenames are indicated by specifying a questions mark "?" instead of a
794
slash, followed by the template name. Thus, the selector line for our
795
dynamic file name would look as follows:</p>
796
<blockquote>
797
<code>*.* ?DynFile</code>
798
</blockquote>
799
<p>That's all you need to do. Rsyslog will now automatically
800
generate file names for you and store the right messages into the right
801
files. Please note that the minus sign also works with dynamic file
802
name selectors. Thus, to avoid syncing, you may use</p>
803
<blockquote>
804
<code>*.* -?DynFile</code></blockquote>
805
<p>And of course you can use templates to specify the output
806
format:</p>
807
<blockquote>
808
<code>*.* ?DynFile;MyTemplate</code></blockquote>
809
<p><b>A word of caution:</b> rsyslog creates files as
810
needed. So if a new host is using your syslog server, rsyslog will
811
automatically create a new file for it.</p>
812
<p><b>Creating directories is also supported</b>. For
813
example you can use the hostname as directory and the program name as
814
file name:</p>
815
<blockquote>
816
<code>$template DynFile,"/var/log/%HOSTNAME%/%programname%.log"</code></blockquote>
817
<h3>Named Pipes</h3>
818
<p>This version of rsyslogd(8) has support for logging output to
819
named pipes (fifos). A fifo or named pipe can be used as a destination
820
for log messages by prepending a pipe symbol ("|'') to the name of the
821
file. This is handy for debugging. Note that the fifo must be created
822
with the mkfifo(1) command before rsyslogd(8) is started.</p>
823
<h3>Terminal and Console</h3>
824
<p>If the file you specified is a tty, special tty-handling is
825
done, same with /dev/console.</p>
826
<h3>Remote Machine</h3>
827
<p>Rsyslogd provides full remote logging, i.e. is able to send
828
messages to a remote host running rsyslogd(8) and to receive messages
829
from remote hosts. Using this feature you're able to control all syslog
830
messages on one host, if all other machines will log remotely to that.
831
This tears down<br>
832
administration needs.<br>
833
<br>
834
<b>Please note that this version of rsyslogd by default does NOT
835
forward messages it has received from the network to another host.
836
Specify the "-h" option to enable this.</b></p>
837
<p>To forward messages to another host, prepend the hostname with
838
the at sign ("@"). A single at sign means that messages will
839
be forwarded via UDP protocol (the standard for syslog). If you prepend
840
two at signs ("@@"), the messages will be transmitted via TCP. Please
841
note that plain TCP based syslog is not officially standardized, but
842
most major syslogds support it (e.g. syslog-ng or WinSyslog). The
843
forwarding action indicator (at-sign) can be followed by one or more
844
options. If they are given, they must be immediately (without a space)
845
following the final at sign and be enclosed in parenthesis. The
846
individual options must be separated by commas. The following options
847
are right now defined:</p>
848
<table id="table2" border="1" width="100%">
849
<tbody>
850
<tr>
851
<td>
852
<p align="center"><b>z<number></b></p>
853
</td>
854
<td>Enable zlib-compression for the message. The
855
<number> is the compression level. It can be 1 (lowest
856
gain, lowest CPU overhead) to 9 (maximum compression, highest CPU
857
overhead). The level can also be 0, which means "no compression". If
858
given, the "z" option is ignored. So this does not make an awful lot of
859
sense. There is hardly a difference between level 1 and 9 for typical
860
syslog messages. You can expect a compression gain between 0% and 30%
861
for typical messages. Very chatty messages may compress up to 50%, but
862
this is seldom seen with typically traffic. Please note that rsyslogd
863
checks the compression gain. Messages with 60 bytes or less will never
864
be compressed. This is because compression gain is pretty unlikely and
865
we prefer to save CPU cycles. Messages over that size are always
866
compressed. However, it is checked if there is a gain in compression
867
and only if there is, the compressed message is transmitted. Otherwise,
868
the uncompressed messages is transmitted. This saves the receiver CPU
869
cycles for decompression. It also prevents small message to actually
870
become larger in compressed form.
871
<p><b>Please note that when a TCP transport is used,
872
compression will also turn on syslog-transport-tls framing. See the "o"
873
option for important information on the implications.</b></p>
874
<p>Compressed messages are automatically detected and
875
decompressed by the receiver. There is nothing that needs to be
876
configured on the receiver side.</p>
877
</td>
878
</tr>
879
<tr>
880
<td>
881
<p align="center"><b>o</b></p>
882
</td>
883
<td><b>This option is experimental. Use at your own
884
risk and only if you know why you need it! If in doubt, do NOT turn it
885
on.</b>
886
<p>This option is only valid for plain TCP based
887
transports. It selects a different framing based on IETF internet draft
888
syslog-transport-tls-06. This framing offers some benefits over
889
traditional LF-based framing. However, the standardization effort is
890
not yet complete. There may be changes in upcoming versions of this
891
standard. Rsyslog will be kept in line with the standard. There is some
892
chance that upcoming changes will be incompatible to the current
893
specification. In this case, all systems using -transport-tls framing
894
must be upgraded. There will be no effort made to retain compatibility
895
between different versions of rsyslog. The primary reason for that is
896
that it seems technically impossible to provide compatibility between
897
some of those changes. So you should take this note very serious. It is
898
not something we do not *like* to do (and may change our mind if enough
899
people beg...), it is something we most probably *can not* do for
900
technical reasons (aka: you can beg as much as you like, it won't
901
change anything...).</p>
902
<p>The most important implication is that compressed syslog
903
messages via TCP must be considered with care. Unfortunately, it is
904
technically impossible to transfer compressed records over traditional
905
syslog plain tcp transports, so you are left with two evil choices...</p>
906
</td>
907
</tr>
908
</tbody>
909
</table>
910
<p><br>
911
The hostname may be followed by a colon and the destination port.</p>
912
<p>The following is an example selector line with forwarding:</p>
913
<p>*.* @@(o,z9)192.168.0.1:1470</p>
914
<p>In this example, messages are forwarded via plain TCP with
915
experimental framing and maximum compression to the host 192.168.0.1 at
916
port 1470.</p>
917
<p>*.* @192.168.0.1</p>
918
<p>In the example above, messages are forwarded via UDP to the
919
machine 192.168.0.1, the destination port defaults to 514. Messages
920
will not be compressed.</p>
921
<p>Note that IPv6 addresses contain colons. So if an IPv6 address is specified
922
in the hostname part, rsyslogd could not detect where the IP address ends
923
and where the port starts. There is a syntax extension to support this:
924
put squary brackets around the address (e.g. "[2001::1]"). Square
925
brackets also work with real host names and IPv4 addresses, too.
926
<p>A valid sample to send messages to the IPv6 host 2001::1 at port 515
927
is as follows:
928
<p>*.* @[2001::1]:515
929
<p>This works with TCP, too.
930
<p><b>Note to sysklogd users:</b> sysklogd does <b>not</b>
931
support RFC 3164 format, which is the default forwarding template in
932
rsyslog. As such, you will experience duplicate hostnames if rsyslog is
933
the sender and sysklogd is the receiver. The fix is simple: you need to
934
use a different template. Use that one:</p>
935
<p class="MsoPlainText">$template
936
sysklogd,"<%PRI%>%TIMESTAMP% %syslogtag%%msg%\""<br>
937
*.* @192.168.0.1;sysklogd</p>
938
<h3>List of Users</h3>
939
<p>Usually critical messages are also directed to "root'' on
940
that machine. You can specify a list of users that shall get the
941
message by simply writing the login. You may specify more than one user
942
by separating them with commas (",''). If they're logged in they get
943
the message. Don't think a mail would be sent, that might be too late.</p>
944
<h3>Everyone logged on</h3>
945
<p>Emergency messages often go to all users currently online to
946
notify them that something strange is happening with the system. To
947
specify this wall(1)-feature use an asterisk ("*'').</p>
948
<h3>Call Plugin</h3>
949
<p>This is a generic way to call an output plugin. The plugin
950
must support this functionality. Actual parameters depend on the
951
module, so see the module's doc on what to supply. The general syntax
952
is as follows:</p>
953
<p>:modname:params;template</p>
954
<p>Currently, the ommysql database output module supports this
955
syntax (in addtion to the ">" syntax it traditionally
956
supported). For ommysql, the module name is "ommysql" and the params
957
are the traditional ones. The ;template part is not module specific, it
958
is generic rsyslog functionality available to all modules.</p>
959
<p>As an example, the ommysql module may be called as follows:</p>
960
<p>:ommysql:dbhost,dbname,dbuser,dbpassword;dbtemplate</p>
961
<p>For details, please see the "Database Table" section of this
962
documentation.</p>
963
<p>Note: as of this writing, the ":modname:" part is hardcoded
964
into the module. So the name to use is not necessarily the name the
965
module's plugin file is called.</p>
966
<h3>Database Table</h3>
967
<p>This allows logging of the message to a database table.
968
Currently, only MySQL databases are supported. However, other database
969
drivers will most probably be developed as plugins. By default, a <a href="http://www.monitorware.com/">MonitorWare</a>-compatible
970
schema is required for this to work. You can create that schema with
971
the createDB.SQL file that came with the rsyslog package. You can also<br>
972
use any other schema of your liking - you just need to define a proper
973
template and assign this template to the action.<br>
974
<br>
975
The database writer is called by specifying a greater-then sign
976
(">") in front of the database connect information. Immediately
977
after that<br>
978
sign the database host name must be given, a comma, the database name,
979
another comma, the database user, a comma and then the user's password.
980
If a specific template is to be used, a semicolon followed by the
981
template name can follow the connect information. This is as follows:<br>
982
<br>
983
>dbhost,dbname,dbuser,dbpassword;dbtemplate</p>
984
<p><b>Important: to use the database functionality, the
985
MySQL output module must be loaded in the config file</b> BEFORE
986
the first database table action is used. This is done by placing the</p>
987
<p><code><b>$ModLoad ommysql</b></code></p>
988
<p>directive some place above the first use of the database write
989
(we recommend doing at the the beginning of the config file).</p>
990
<h3>Discard</h3>
991
<p>If the discard action is carried out, the received message is
992
immediately discarded. No further processing of it occurs. Discard has
993
primarily been added to filter out messages before carrying on any
994
further processing. For obvious reasons, the results of "discard" are
995
depending on where in the configuration file it is being used. Please
996
note that once a message has been discarded there is no way to retrieve
997
it in later configuration file lines.</p>
998
<p>Discard can be highly effective if you want to filter out some
999
annoying messages that otherwise would fill your log files. To do that,
1000
place the discard actions early in your log files. This often plays
1001
well with property-based filters, giving you great freedom in
1002
specifying what you do not want.</p>
1003
<p>Discard is just the single tilde character with no further
1004
parameters:</p>
1005
<p>~</p>
1006
<p>For example,</p>
1007
<p>*.* ~</p>
1008
<p>discards everything (ok, you can achive the same by not
1009
running rsyslogd at all...).</p>
1010
<h3>Output Channel</h3>
1011
<p>Binds an output channel definition (see there for details) to
1012
this action. Output channel actions must start with a $-sign, e.g. if
1013
you would like to bind your output channel definition "mychannel" to
1014
the action, use "$mychannel". Output channels support template
1015
definitions like all all other actions.</p>
1016
<h3>Shell Execute</h3>
1017
<p>This executes a program in a subshell. The program is passed
1018
the template-generated message as the only command line parameter.
1019
Rsyslog waits until the program terminates and only then continues to
1020
run.</p>
1021
<p>^program-to-execute;template</p>
1022
<p>The program-to-execute can be any valid executable. It
1023
receives the template string as a single parameter (argv[1]).</p>
1024
<p><b>WARNING:</b> The Shell Execute action was added
1025
to serve an urgent need. While it is considered reasonable save when
1026
used with some thinking, its implications must be considered. The
1027
current implementation uses a system() call to execute the command.
1028
This is not the best way to do it (and will hopefully changed in
1029
further releases). Also, proper escaping of special characters is done
1030
to prevent command injection. However, attackers always find smart ways
1031
to circumvent escaping, so we can not say if the escaping applied will
1032
really safe you from all hassles. Lastly, rsyslog will wait until the
1033
shell command terminates. Thus, a program error in it (e.g. an infinite
1034
loop) can actually disable rsyslog. Even without that, during the
1035
programs run-time no messages are processed by rsyslog. As the IP
1036
stacks buffers are quickly overflowed, this bears an increased risk of
1037
message loss. You must be aware of these implications. Even though they
1038
are severe, there are several cases where the "shell execute" action is
1039
very useful. This is the reason why we have included it in its current
1040
form. To mitigate its risks, always a) test your program thoroughly, b)
1041
make sure its runtime is as short as possible (if it requires a longer
1042
run-time, you might want to spawn your own sub-shell asynchronously),
1043
c) apply proper firewalling so that only known senders can send syslog
1044
messages to rsyslog. Point c) is especially important: if rsyslog is
1045
accepting message from any hosts, chances are much higher that an
1046
attacker might try to exploit the "shell execute" action.</p>
1047
<h2>TEMPLATE NAME</h2>
1048
<p>Every ACTION can be followed by a template name. If so, that
1049
template is used for message formatting. If no name is given, a
1050
hard-coded default template is used for the action. There can only be
1051
one template name for each given action. The default template is
1052
specific to each action. For a description of what a template is and
1053
what you can do with it, see "TEMPLATES" at the top of this document.</p>
1054
<h2>EXAMPLES</h2>
1055
<p>Below are example for templates and selector lines. I hope
48
<h2><a href="rsyslog_conf_templates.html">Templates</a></h2>
49
<h2><a href="rsyslog_conf_output.html">Output Channels</a></h2>
50
<h2><a href="rsyslog_conf_filter.html">Filter Conditions</a></h2>
51
<h2><a href="rsyslog_conf_actions.html">Actions</a></h2>
52
<h2><a href="rsyslog_conf_examples.html">Examples</a></h2>
53
<p>Here you will find examples for templates and selector lines. I hope
1056
54
they are self-explanatory. If not, please see
1057
55
www.monitorware.com/rsyslog/ for advise.</p>
1058
<h3>TEMPLATES</h3>
1059
<p>Please note that the samples are split across multiple lines.
1060
A template MUST NOT actually be split across multiple lines.<br>
1061
<br>
1062
A template that resembles traditional syslogd file output:<br>
1063
$template TraditionalFormat,"%timegenerated% %HOSTNAME%<br>
1064
%syslogtag%%msg:::drop-last-lf%\n"<br>
1065
<br>
1066
A template that tells you a little more about the message:<br>
1067
$template
1068
precise,"%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,<br>
1069
%syslogtag%,%msg%\n"<br>
1070
<br>
1071
A template for RFC 3164 format:<br>
1072
$template RFC3164fmt,"<%PRI%>%TIMESTAMP% %HOSTNAME%
1073
%syslogtag%%msg%"<br>
1074
<br>
1075
A template for the format traditonally used for user messages:<br>
1076
$template usermsg," XXXX%syslogtag%%msg%\n\r"<br>
1077
<br>
1078
And a template with the traditonal wall-message format:<br>
1079
$template wallmsg,"\r\n\7Message from syslogd@%HOSTNAME% at
1080
%timegenerated%<br>
1081
<br>
1082
A template that can be used for the database write (please note the SQL<br>
1083
template option)<br>
1084
$template MySQLInsert,"insert iut, message, receivedat values<br>
1085
('%iut%', '%msg:::UPPERCASE%', '%timegenerated:::date-mysql%')<br>
1086
into systemevents\r\n", SQL<br>
1087
<br>
1088
The following template emulates <a href="http://www.winsyslog.com/en/">WinSyslog</a>
1089
format (it's an <a href="http://www.adiscon.com/en/">Adiscon</a>
1090
format, you do not feel bad if you don't know it ;)). It's interesting
1091
to see how it takes different parts out of the date stamps. What
1092
happens is that the date stamp is split into the actual date and time
1093
and the these two are combined with just a comma in between them.<br>
1094
<br>
1095
$template WinSyslogFmt,"%HOSTNAME%,%timegenerated:1:10:date-rfc3339%,<br>
1096
%timegenerated:12:19:date-rfc3339%,%timegenerated:1:10:date-rfc3339%,<br>
1097
%timegenerated:12:19:date-rfc3339%,%syslogfacility%,%syslogpriority%,<br>
1098
%syslogtag%%msg%\n"</p>
1099
<h3>SELECTOR LINES</h3>
1100
<p># Store critical stuff in critical<br>
1101
#<br>
1102
*.=crit;kern.none /var/adm/critical<br>
1103
<br>
1104
This will store all messages with the priority crit in the file
1105
/var/adm/critical, except for any kernel message.<br>
1106
<br>
1107
<br>
1108
# Kernel messages are first, stored in the kernel<br>
1109
# file, critical messages and higher ones also go<br>
1110
# to another host and to the console. Messages to<br>
1111
# the host finlandia are forwarded in RFC 3164<br>
1112
# format (using the template defined above).<br>
1113
#<br>
1114
kern.* /var/adm/kernel<br>
1115
kern.crit @finlandia;RFC3164fmt<br>
1116
kern.crit /dev/console<br>
1117
kern.info;kern.!err /var/adm/kernel-info<br>
1118
<br>
1119
The first rule direct any message that has the kernel facility to the
1120
file /var/adm/kernel.<br>
1121
<br>
1122
The second statement directs all kernel messages of the priority crit
1123
and higher to the remote host finlandia. This is useful, because if the
1124
host crashes and the disks get irreparable errors you might not be able
1125
to read the stored messages. If they're on a remote host, too, you
1126
still can try to find out the reason for the crash.<br>
1127
<br>
1128
The third rule directs these messages to the actual console, so the
1129
person who works on the machine will get them, too.<br>
1130
<br>
1131
The fourth line tells rsyslogd to save all kernel messages that come
1132
with priorities from info up to warning in the file
1133
/var/adm/kernel-info. Everything from err and higher is excluded.<br>
1134
<br>
1135
<br>
1136
# The tcp wrapper loggs with mail.info, we display<br>
1137
# all the connections on tty12<br>
1138
#<br>
1139
mail.=info /dev/tty12<br>
1140
<br>
1141
This directs all messages that uses mail.info (in source LOG_MAIL |
1142
LOG_INFO) to /dev/tty12, the 12th console. For example the tcpwrapper
1143
tcpd(8) uses this as it's default.<br>
1144
<br>
1145
<br>
1146
# Store all mail concerning stuff in a file<br>
1147
#<br>
1148
mail.*;mail.!=info /var/adm/mail<br>
1149
<br>
1150
This pattern matches all messages that come with the mail facility,
1151
except for the info priority. These will be stored in the file
1152
/var/adm/mail.<br>
1153
<br>
1154
<br>
1155
# Log all mail.info and news.info messages to info<br>
1156
#<br>
1157
mail,news.=info /var/adm/info<br>
1158
<br>
1159
This will extract all messages that come either with mail.info or with
1160
news.info and store them in the file /var/adm/info.<br>
1161
<br>
1162
<br>
1163
# Log info and notice messages to messages file<br>
1164
#<br>
1165
*.=info;*.=notice;\<br>
1166
mail.none /var/log/messages<br>
1167
<br>
1168
This lets rsyslogd log all messages that come with either the info or
1169
the notice facility into the file /var/log/messages, except for all<br>
1170
messages that use the mail facility.<br>
1171
<br>
1172
<br>
1173
# Log info messages to messages file<br>
1174
#<br>
1175
*.=info;\<br>
1176
mail,news.none /var/log/messages<br>
1177
<br>
1178
This statement causes rsyslogd to log all messages that come with the
1179
info priority to the file /var/log/messages. But any message coming
1180
either with the mail or the news facility will not be stored.<br>
1181
<br>
1182
<br>
1183
# Emergency messages will be displayed using wall<br>
1184
#<br>
1185
*.=emerg *<br>
1186
<br>
1187
This rule tells rsyslogd to write all emergency messages to all
1188
currently logged in users. This is the wall action.<br>
1189
<br>
1190
<br>
1191
# Messages of the priority alert will be directed<br>
1192
# to the operator<br>
1193
#<br>
1194
*.alert root,rgerhards<br>
1195
<br>
1196
This rule directs all messages with a priority of alert or higher to
1197
the terminals of the operator, i.e. of the users "root'' and
1198
"rgerhards'' if they're logged in.<br>
1199
<br>
1200
<br>
1201
*.* @finlandia<br>
1202
<br>
1203
This rule would redirect all messages to a remote host called
1204
finlandia. This is useful especially in a cluster of machines where all
1205
syslog messages will be stored on only one machine.<br>
1206
<br>
1207
In the format shown above, UDP is used for transmitting the message.
1208
The destination port is set to the default auf 514. Rsyslog is also
1209
capable of using much more secure and reliable TCP sessions for message
1210
forwarding. Also, the destination port can be specified. To select TCP,
1211
simply add one additional @ in front of the host name (that is, @host
1212
is UPD, @@host is TCP). For example:<br>
1213
<br>
1214
<br>
1215
*.* @@finlandia<br>
1216
<br>
1217
To specify the destination port on the remote machine, use a colon
1218
followed by the port number after the machine name. The following
1219
forwards to port 1514 on finlandia:<br>
1220
<br>
1221
<br>
1222
*.* @@finlandia:1514<br>
1223
<br>
1224
This syntax works both with TCP and UDP based syslog. However, you will
1225
probably primarily need it for TCP, as there is no well-accepted port
1226
for this transport (it is non-standard). For UDP, you can usually stick
1227
with the default auf 514, but might want to modify it for security rea-<br>
1228
sons. If you would like to do that, it's quite easy:<br>
1229
<br>
1230
<br>
1231
*.* @finlandia:1514<br>
1232
<br>
1233
<br>
1234
<br>
1235
*.* >dbhost,dbname,dbuser,dbpassword;dbtemplate<br>
1236
<br>
1237
This rule writes all message to the database "dbname" hosted on
1238
"dbhost". The login is done with user "dbuser" and password
1239
"dbpassword". The actual table that is updated is specified within the
1240
template (which contains the insert statement). The template is called
1241
"dbtemplate" in this case.</p>
1242
<p>:msg,contains,"error" @errorServer</p>
1243
<p>This rule forwards all messages that contain the word "error"
1244
in the msg part to the server "errorServer". Forwarding is via UDP.
1245
Please note the colon in fron</p>
1246
<h2>CONFIGURATION FILE SYNTAX DIFFERENCES</h2>
56
<h2>Configuration File Syntax Differences</h2>
1247
57
<p>Rsyslogd uses a slightly different syntax for its
1248
58
configuration file than the original BSD sources. Originally all
1249
59
messages of a specific priority and above were forwarded to the log
1258
68
<a href="features.html">features</a> (like template
1259
69
and database support). For obvious reasons, the syntax for defining
1260
70
such features is available in rsyslogd, only.</p>
1261
</body></html>
71
72
<p>[<a href="rsyslog_conf.html">back to top</a>]
73
[<a href="manual.html">manual index</a>]
74
[<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
75
<p><font size="2">This documentation is part of the
76
<a href="http://www.rsyslog.com/">rsyslog</a> project.<br>
77
Copyright © 2008 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
78
<a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL
79
version 2 or higher.</font></p>
80
</body>
81
</html>
82
>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1