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
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
|
<html>
<head>
<title>rsyslog.conf file</title>
</head>
<body>
<h1>rsyslog.conf configuration file</h1>
<p><b>This document is currently being enhanced. Please pardon its current
appearance.</b></p>
<p><b>Rsyslogd is configured via the rsyslog.conf file</b>, typically found in
/etc. By default, rsyslog reads the file /etc/rsyslog.conf.</p>
<p>While rsyslogd contains enhancements over standard syslogd, efforts have been
made to keep the configuration file as compatible as possible. While, for
obvious reasons, <a href="features.html">enhanced features</a> require a
different config file syntax, rsyslogd should be able to work with a standard
syslog.conf file. This is especially useful while you are migrating from syslogd
to rsyslogd.</p>
<h2>Basic Structure</h2>
<p>Every rule consists of two fields, a selector field and an action field.
These two fields are separated by one or more spaces or tabs. The selector field
specifies a pattern of facilities and priorities belonging to the specified
action.<br>
<br>
Lines starting with a hash mark (``#'') and empty lines are ignored.
<h2>Templates</h2>
<p>Templates are a key feature of rsyslog. They allow to specify any format a user
might want. Every output in rsyslog uses templates - this holds true for files,
user messages and so on. The database writer expects its template to be a proper
SQL statement - so this is highly customizable too. You might ask how does all
of this work when no templates at all are specified. Good question ;) The answer
is simple, though. Templates compatible with the stock syslogd formats are
hardcoded into rsyslogd. So if no template is specified, we use one of these
hardcoded templates. Search for "template_" in syslogd.c and you will find the
hardcoded ones.</p>
<p>A template consists of a template directive, a name, the actual template text
and optional options. A sample is:</p>
<blockquote><code>$template MyTemplateName,"\7Text %property% some more text\n",<options></code></blockquote>
<p>The "$template" is the template directive. It tells rsyslog that this line
contains a template. "MyTemplateName" is the template name. All
other config lines refer to this name. The text within quotes is the actual
template text. The backslash is an escape character, much as it is in C. It does
all these "cool" things. For example, \7 rings the bell (this is an ASCII
value), \n is a new line. C programmers and perl coders have the advantage of
knowing this, but the set in rsyslog is a bit restricted currently.
<p>
All text in the template is used literally, except for things within percent
signs. These are properties and allow you access to the contents of the syslog
message. Properties are accessed via the property replacer (nice name, huh) and
it can do cool things, too. For example, it can pick a substring or do
date-specific formatting. More on this is below, on some lines of the property
replacer.<br>
<br>
The <options> part is optional. It carries options influencing the template as
whole. See details below. Be sure NOT to mistake template options with property
options - the later ones are processed by the property replacer and apply to a
SINGLE property, only (and not the whole template).<br>
<br>
Template options are case-insensitive. Currently defined are: </p>
<p><b>sql</b> - format the string suitable for a SQL statement. This will
replace single quotes ("'") by two single quotes ("''") inside each field. This
option MUST be specified when a template is used for writing to a database,
otherwise SQL injection might occur.<br>
<br>
Please note that the database writer *checks* that the sql option is present in
the template. If it is not present, the write database action is disabled. This
is to guard you against accidential forgetting it and then becoming vulnerable
to SQL injection. The sql option can also be useful with files - especially if
you want to import them into a database on another machine for performance
reasons. However, do NOT use it if you do not have a real need for it - among
others, it takes some toll on the processing time. Not much, but on a really
busy system you might notice it ;)<br>
<br>
To escape:<br>
% = \%<br>
\ = \\ --> '\' is used to escape (as in C)<br>
$template TraditionalFormat,%timegenerated% %HOSTNAME% %syslogtag%%msg%\n"<br>
<br>
Properties can be accessed by the <a href="property_replacer.html">property replacer</a>
(see there for details).</p>
<h2>Output Channels</h2>
<p>Output Channels are a new concept first introduced in rsyslog 0.9.0. As of this
writing, it is still unclear if they will stay in rsyslog or go away. So if you
use them, be prepared to change you configuration file syntax when you upgrade
to a later release.<br>
<br>
The idea behind output channel definitions is that it shall provide an umbrella
for any type of output that the user might want. In essence,<br>
this is the "file" part of selector lines (and this is why we are not sure
output channel syntax will stay after the next review). There is a<br>
difference, though: selector channels both have filter conditions (currently
facility and severity) as well as the output destination. Output channels define
the output defintion, only. As of this build, they can only be used to write to
files - not pipes, ttys or whatever else. If we stick with output channels, this
will change over time.</p>
<p>In concept, an output channel includes everything needed to know about an
output actions. In practice, the current implementation only carries<br>
a filename, a maximum file size and a command to be issued when this file size
is reached. More things might be present in future version, which might also
change the syntax of the directive.</p>
<p>Output channels are defined via an $outchannel directive. It's syntax is as
follows:<br>
<br>
$outchannel name,file-name,max-size,action-on-max-size<br>
<br>
name is the name of the output channel (not the file), file-name is the file
name to be written to, max-size the maximum allowed size and action-on-max-size
a command to be issued when the max size is reached.<br>
<br>
Please note that max-size is queried BEFORE writing the log message to the file.
So be sure to set this limit reasonably low so that any message might fit. For
the current release, setting it 1k lower than you expected is helpful. The
max-size must always be specified in bytes - there are no special symbols (like
1k, 1m,...) at this point of development.<br>
<br>
Keep in mind that $outchannel just defines a channel with "name". It does not
activate it. To do so, you must use a selector line (see below). That selector
line includes the channel name plus an $ sign in front of it. A sample might be:<br>
<br>
*.* $mychannel<br>
<br>
In its current form, output channels primarily provide the ability to size-limit
an output file. To do so, specify a maximum size. When this size is reachead,
rsyslogd will execute the action-on-max-size command and then reopen the file
and retry. The command should be something like a log rotation script or a
similar thing.</p>
<blockquote>
<p><b>WARNING</b>
<p>The current command logic is a quick hack. It simply issues the command via a
system() call, which is very dirty. Don't make rsyslogd a suid
binary and use action-on-max-size commands - this will mess up things. Fixing
this is on top of the todo list and the fix will hopefully
appear soon.</p>
</blockquote>
<p>If there is no action-on-max-size command or the command did not resolve the
situation, the file is closed and never reopened by rsyslogd (except, of course,
by huping it). This logic was integrated when we first experienced severe issues
with files larger 2gb, which could lead to rsyslogd dumping core. In such cases,
it is more appropriate to stop writing to a single file. Meanwhile, rsyslogd has
been fixed to support files larger 2gb, but obviously only on file systems and
operating system versions that do so. So it can still make sense to enforce a
2gb file size limit.</p>
<h2>SELECTORS</h2>
<p>The selector field itself again consists of two parts, a facility and a
priority, separated by a period (``.''). Both parts are case insenstive and can
also be specified as decimal numbers, but don't do that, you have been warned.
Both facilities and priorities are described in rsyslog(3). The names mentioned
below correspond to the similar LOG_-values in /usr/include/rsyslog.h.<br><br>The facility is one of the following keywords: auth, authpriv, cron, daemon,
kern, lpr, mail, mark, news, security (same as auth), syslog, user, uucp and
local0 through local7. The keyword security should not be used anymore and mark
is only for internal use and therefore should not be used in applications.
Anyway, you may want to specify and redirect these messages here. The facility
specifies the subsystem that produced the message, i.e. all mail programs log
with the mail facility (LOG_MAIL) if they log using syslog.<br><br>Please note that the upcoming next syslog-RFC specifies many more facilities.
Support for them will be added in a future version of rsyslog, which might
require changes to existing configuration files.<br><br>The priority is one of the following keywords, in ascending order: debug, info,
notice, warning, warn (same as warning), err, error (same as err), crit, alert,
emerg, panic (same as emerg). The keywords error, warn and panic are deprecated
and should not be used anymore. The priority defines the severity of the message<br>
<br>The behavior of the original BSD syslogd is that all messages of the specified
priority and higher are logged according to the given action. This rsyslogd(8)
behaves the same, but has some extensions.<br><br>In addition to the above mentioned names the rsyslogd(8) understands the
following extensions: An asterisk (``*'') stands for all facilities or all
priorities, depending on where it is used (before or after the period). The
keyword none stands for no priority of the given facility.<br><br>You can specify multiple facilities with the same priority pattern in one
statement using the comma (``,'') operator. You may specify as much facilities
as you want. Remember that only the facility part from such a statement is
taken, a priority part would be skipped.</p>
<p>Multiple selectors may be specified for a single action using the semicolon
(``;'') separator. Remember that each selector in the selector field is capable
to overwrite the preceding ones. Using this behavior you can exclude some
priorities from the pattern.</p>
<p>Rsyslogd(8) has a syntax extension to the original BSD source, that makes its
use more intuitively. You may precede every priority with an equation sign
(``='') to specify only this single priority and not any of the above. You may
also (both is valid, too) precede the priority with an exclamation mark (``!'')
to ignore all that priorities, either exact this one or this and any higher
priority. If you use both extensions than the exclamation mark must occur before
the equation sign, just use it intuitively.</p>
<h2>ACTIONS</h2>
<p>The action field of a rule describes what to do with the message. In general,
message content is written to a kind of "logfile". But also other actions might
be done, like writing to a database table or forwarding to another host.<br>
<br>
Templates can be used with all actions. If used, the specified template is used
to generate the message content (instead of the default template). To specify a
template, write a semicolon after the action value immediately followed by the
template name.<br>
<br>
Beware: templates MUST be defined BEFORE they are used. It is OK to define some
templates, then use them in selector lines, define more templates and use use
them in the following selector lines. But it is NOT permitted to use a template
in a selectore line that is above its definition. If you do this, the selector
line will be ignored.</p>
<h3>Regular File</h3>
<p>Typically messages are logged to real files. The file has to be specified with
full pathname, beginning with a slash ``/''.<br>
<br>
You may prefix each entry with the minus ``-'' sign to omit syncing the file
after every logging. Note that you might lose information if the system crashes
right behind a write attempt. Nevertheless this might give you back some
performance, especially if you run programs that use<br>
logging in a very verbose manner.</p>
<p>If your system is connected to a reliable UPS and you receive lots of log
data (e.g. firewall logs), it might be a very good idea to turn of<br>
syncing by specifying the "-" in front of the file name. </p>
<h3>Named Pipes</h3>
<p>This version of rsyslogd(8) has support for logging output to named pipes (fifos).
A fifo or named pipe can be used as a destination for log messages by prepending
a pipe symbol (``|'') to the name of the file. This is handy for debugging. Note
that the fifo must be created with the mkfifo(1) command before rsyslogd(8) is
started.</p>
<h3>Terminal and Console</h3>
<p>If the file you specified is a tty, special tty-handling is done, same with
/dev/console.</p>
<h3>Remote Machine</h3>
<p>Rsyslogd provides full remote logging, i.e. is able to send messages to a
remote host running rsyslogd(8) and to receive messages from remote hosts. The
remote host won't forward the message again, it will just log them locally. To
forward messages to another host, prepend the hostname with the at sign (``@'').<br>
<br>
Using this feature you're able to control all syslog messages on one host, if
all other machines will log remotely to that. This tears down<br>
administration needs.<br>
<br>
Please note that this version of rsyslogd by default does NOT forward messages
it has received from the network to another host. Specify the<br>
-h option to enable this.</p>
<h3>List of Users</h3>
<p>Usually critical messages are also directed to ``root'' on that machine. You can
specify a list of users that shall get the message by simply writing the login.
You may specify more than one user by separating them with commas (``,''). If
they're logged in they get the message. Don't think a mail would be sent, that
might be too late.</p>
<h3>Everyone logged on</h3>
<p>Emergency messages often go to all users currently online to notify them that
something strange is happening with the system. To specify this wall(1)-feature
use an asterisk (``*'').</p>
<h3>Database Table</h3>
<p>This allows logging of the message to a database table. Currently, only MySQL
databases are supported. By default, a MonitorWare-compatible schema is required
for this to work. You can create that schema with the createDB.SQL file that
came with the rsyslog package. You can also<br>
use any other schema of your liking - you just need to define a proper template
and assign this template to the action.<br>
<br>
The database writer is called by specifying a greater-then sign (">") in front
of the database connect information. Immediately after that<br>
sign the database host name must be given, a comma, the database name, another
comma, the database user, a comma and then the user's password. If a specific
template is to be used, a semicolong followed by the template name can follow
the connect information. This is as follows:<br>
<br>
>dbhost,dbname,dbuser,dbpassword;dbtemplate</p>
<h3>Output Channel</h3>
<p>Binds an output channel definition (see there for details) to this action.
Output channel actions must start with a $-sign, e.g. if you would like to bind
your output channel definition "mychannel" to the action, use "$mychannel".
Output channels support template definitions like all all other actions.</p>
<h2>TEMPLATE NAME</h2>
<p>Every ACTION can be followed by a template name. If so, that template is used
for message formatting. If no name is given, a hardcoded default template is
used for the action. There can only be one template name for each given action.
The default template is specific to each action. For a description of what a
template is and what you can do with it, see "TEMPLATES" at the top of this
document.</p>
<h2>EXAMPLES</h2>
<p>Below are example for templates and selector lines. I hope they are
self-explanatory. If not, please see www.monitorware.com/rsyslog/ for advise.</p>
<h3>TEMPLATES</h3>
<p>Please note that the samples are split across multiple lines. A template MUST
NOT actually be split across multiple lines.<br>
<br>
A template that resambles traditional syslogd file output:<br>
$template TraditionalFormat,"%timegenerated% %HOSTNAME%<br>
%syslogtag%%msg:::drop-last-lf%\n"<br>
<br>
A template that tells you a little more about the message:<br>
$template precise,"%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,<br>
%syslogtag%,%msg%\n"<br>
<br>
A template for RFC 3164 format:<br>
$template RFC3164fmt,"<%PRI%>%TIMESTAMP% %HOSTNAME% %syslogtag%%msg%"<br>
<br>
A template for the format traditonally used for user messages:<br>
$template usermsg," XXXX%syslogtag%%msg%\n\r"<br>
<br>
And a template with the traditonal wall-message format:<br>
$template wallmsg,"\r\n\7Message from syslogd@%HOSTNAME% at %timegenerated%<br>
<br>
A template that can be used for the database write (please note the SQL<br>
template option)<br>
$template MySQLInsert,"insert iut, message, receivedat values<br>
('%iut%', '%msg:::UPPERCASE%', '%timegenerated:::date-mysql%')<br>
into systemevents\r\n", SQL<br>
<br>
The following template emulates <a href="http://www.winsyslog.com/en/">WinSyslog</a>
format (it's an <a href="http://www.adiscon.com/en/">Adiscon</a> format, you do
not feel bad if you don't know it ;)). It's interesting to see how it takes
different parts out of the date stamps. What happens is that the date stamp is
split into the actual date and time and the these two are combined with just a
comma in between them.<br>
<br>
$template WinSyslogFmt,"%HOSTNAME%,%timegenerated:1:10:date-rfc3339%,<br>
%timegenerated:12:19:date-rfc3339%,%timegenerated:1:10:date-rfc3339%,<br>
%timegenerated:12:19:date-rfc3339%,%syslogfacility%,%syslogpriority%,<br>
%syslogtag%%msg%\n"</p>
<h3>SELECTOR LINES</h3>
<p># Store critical stuff in critical<br>
#<br>
*.=crit;kern.none /var/adm/critical<br>
<br>
This will store all messages with the priority crit in the file /var/adm/critical,
except for any kernel message.<br>
<br>
<br>
# Kernel messages are first, stored in the kernel<br>
# file, critical messages and higher ones also go<br>
# to another host and to the console. Messages to<br>
# the host finlandia are forwarded in RFC 3164<br>
# format (using the template defined above).<br>
#<br>
kern.* /var/adm/kernel<br>
kern.crit @finlandia;RFC3164fmt<br>
kern.crit /dev/console<br>
kern.info;kern.!err /var/adm/kernel-info<br>
<br>
The first rule direct any message that has the kernel facility to the file /var/adm/kernel.<br>
<br>
The second statement directs all kernel messages of the priority crit and higher
to the remote host finlandia. This is useful, because if the host crashes and
the disks get irreparable errors you might not be able to read the stored
messages. If they're on a remote host, too, you still can try to find out the
reason for the crash.<br>
<br>
The third rule directs these messages to the actual console, so the person who
works on the machine will get them, too.<br>
<br>
The fourth line tells rsyslogd to save all kernel messages that come with
priorities from info up to warning in the file /var/adm/kernel-info. Everything
from err and higher is excluded.<br>
<br>
<br>
# The tcp wrapper loggs with mail.info, we display<br>
# all the connections on tty12<br>
#<br>
mail.=info /dev/tty12<br>
<br>
This directs all messages that uses mail.info (in source LOG_MAIL | LOG_INFO) to
/dev/tty12, the 12th console. For example the tcpwrapper tcpd(8) uses this as
it's default.<br>
<br>
<br>
# Store all mail concerning stuff in a file<br>
#<br>
mail.*;mail.!=info /var/adm/mail<br>
<br>
This pattern matches all messages that come with the mail facility, except for
the info priority. These will be stored in the file /var/adm/mail.<br>
<br>
<br>
# Log all mail.info and news.info messages to info<br>
#<br>
mail,news.=info /var/adm/info<br>
<br>
This will extract all messages that come either with mail.info or with news.info
and store them in the file /var/adm/info.<br>
<br>
<br>
# Log info and notice messages to messages file<br>
#<br>
*.=info;*.=notice;\<br>
mail.none /var/log/messages<br>
<br>
This lets rsyslogd log all messages that come with either the info or the notice
facility into the file /var/log/messages, except for all<br>
messages that use the mail facility.<br>
<br>
<br>
# Log info messages to messages file<br>
#<br>
*.=info;\<br>
mail,news.none /var/log/messages<br>
<br>
This statement causes rsyslogd to log all messages that come with the info
priority to the file /var/log/messages. But any message coming either with the
mail or the news facility will not be stored.<br>
<br>
<br>
# Emergency messages will be displayed using wall<br>
#<br>
*.=emerg *<br>
<br>
This rule tells rsyslogd to write all emergency messages to all currently logged
in users. This is the wall action.<br>
<br>
<br>
# Messages of the priority alert will be directed<br>
# to the operator<br>
#<br>
*.alert root,rgerhards<br>
<br>
This rule directs all messages with a priority of alert or higher to the
terminals of the operator, i.e. of the users ``root'' and ``rgerhards'' if
they're logged in.<br>
<br>
<br>
*.* @finlandia<br>
<br>
This rule would redirect all messages to a remote host called finlandia. This is
useful especially in a cluster of machines where all syslog messages will be
stored on only one machine.<br>
<br>
In the format shown above, UDP is used for transmitting the message. The
destination port is set to the default auf 514. Rsyslog is also capable of using
much more secure and reliable TCP sessions for message forwarding. Also, the
destination port can be specified. To select TCP, simply add one additional @ in
front of the host name (that is, @host is UPD, @@host is TCP). For example:<br>
<br>
<br>
*.* @@finlandia<br>
<br>
To specify the destination port on the remote machine, use a colon followed by
the port number after the machine name. The following forwards to port 1514 on
finlandia:<br>
<br>
<br>
*.* @@finlandia:1514<br>
<br>
This syntax works both with TCP and UDP based syslog. However, you will probably
primarily need it for TCP, as there is no well-accepted port for this transport
(it is non-standard). For UDP, you can usually stick with the default auf 514,
but might want to modify it for security rea-<br>
sons. If you would like to do that, it's quite easy:<br>
<br>
<br>
*.* @finlandia:1514<br>
<br>
<br>
<br>
*.* >dbhost,dbname,dbuser,dbpassword;dbtemplate<br>
<br>
This rule writes all message to the database "dbname" hosted on "dbhost". The
login is done with user "dbuser" and password "dbpassword". The actual table
that is updated is specified within the template (which contains the insert
statement). The template is called "dbtemplate" in this case.</p>
<h2>CONFIGURATION FILE SYNTAX DIFFERENCES</h2>
<p>Rsyslogd uses a slightly different syntax for its configuration file than the
original BSD sources. Originally all messages of a specific priority and above
were forwarded to the log file. The modifiers ``='', ``!'' and ``-'' were added
to make rsyslogd more flexible and to use it in a more intuitive manner.<br>
<br>
The original BSD syslogd doesn't understand spaces as separators between the
selector and the action field.<br>
<br>
When compared to syslogd from sysklogd package, rsyslogd offers additional
<a href="features.html">features</a> (like template and database support). For obvious reasons, the syntax for
defining such features is available
in rsyslogd, only.<br>
</p>
</body>
</html>
|
