summaryrefslogtreecommitdiffstats
path: root/doc/rsyslog_conf.html
blob: 69c8c972c5935e4b2e0a0d48bddf7e593858e323 (plain)
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
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
<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, rsyslogd 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>Rsyslog supports standard sysklogd's configuration file format and extends 
it. So in general, you can take a &quot;normal&quot; syslog.conf and use it together with 
rsyslogd. It will understand everything. However, to use most of rsyslogd's 
unique features, you need to add extended configuration directives.<p>Rsyslogd 
supports the classical, selector-based rule lines. They are still at the heart 
of it and all actions are initiated via rule lines. A rule lines is any line not 
starting with a $ or the comment sign (#). Lines starting with $ carry 
rsyslog-specific directives.<p>Every rule line 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 (&quot;#'') and empty lines are ignored.
<h2>Allowed Sender Lists</h2>
<p>Allowed sender lists can be used to specify which remote systems are allowed 
to send syslog messages to rsyslogd. With them, further hurdles can be placed 
between an attacker and rsyslogd. If a message from a system not in the allowed 
sender list is received, that message is discarded. A diagnostic message is 
logged, so that the fact is recorded (this message can be turned off with the 
&quot;-w&quot; rsyslogd command line option).</p>
<p>Allowed sender lists can be defined for UDP and TCP senders separately. There 
can be as many allowed senders as needed. The syntax to specify them is:</p>
<p><code><b>$AllowedSender &lt;protocol&gt;, ip[/bits], ip[/bits]</b></code></p>
<p>&quot;$AllowedSender&quot; is the directive - it must be written exactly as shown and 
the $ must start at the first column of the line. &quot;&lt;protocol&gt;&quot; is either &quot;UDP&quot; 
or &quot;TCP&quot;. It must immediately be followed by the comma, else you will receive an 
error message. &quot;ip[/bits]&quot; is a machine or network ip address as in 
&quot;192.0.2.0/24&quot; or &quot;127.0.0.1&quot;. If the &quot;/bits&quot; part is omitted, a single host is 
assumed (32 bits or mask 255.255.255.255). &quot;/0&quot; is not allowed, because that 
would match any sending system. If you intend to do that, just remove all $AllowedSender 
directives. If more than 32 bits are requested, they are adjusted to 32. 
Multiple allowed senders can be specified in a comma-delimited list. Also, 
multiple $AllowedSender lines can be given. They are all combined into one UDP 
and one TCP list. Performance-wise, it is good to specify those allowed senders 
with high traffic volume before those with lower volume. As soon as a match is 
found, no further evaluation is necessary and so you can save CPU cycles.</p>
<p>Rsyslogd handles allowed sender detection very early in the code, nearly as 
the first action after receiving a message. This keeps the access to potential 
vulnerable code in rsyslog at a minimum. However, it is still a good idea to 
impose allowed sender limitations via firewalling.</p>
<p><b>WARNING:</b> by UDP design, rsyslogd can not identify a spoofed sender 
address in UDP syslog packets. As such, a malicous person could spoof the adress 
of an allowed sender, send such packets to rsyslogd and rsyslogd would accept 
them as being from the faked sender. To prevent this, use syslog via TCP 
exclusively. If you need to use UDP-based syslog, make sure that you do proper 
egress and ingress filtering at the firewall and router level.</p>
<p>An example for an allowed sender list is as follows:</p>
<p><code><b>$AllowedSender UDP, 127.0.0.1, 192.0.2.0/24</b></code></p>
<h2>UMASK</h2>
<p>The $umask directive allows to specify the rsyslogd processes' umask. If not 
specified, the system-provided default is used. The value given must always be a 
4-digit octal number, with the initial digit being zero. This sample removes all 
umask-restriction:</p>
<p><code><b>$umask 0000</b></code></p>
<p>If $umask is specified multiple times in the configuration file, results may 
be somewhat unpredictable. It is recommended to specify it only once.</p>
<h2>FileCreateMode</h2>
<p>The $FileCreateMode directive allows to specify the creation mode with which 
rsyslogd creates new files. If not specified, the value 0644 is used (which 
retains backward-compatibility with earlier releases). The value given must 
always be a 4-digit octal number, with the initial digit being zero. This sample 
lets rsyslog create files with read and write access only for the users it runs 
under:</p>
<p><code><b>$FileCreateMode 0600</b></code></p>
<p>Please note that the actual permission depend on rsyslogd's process umask. If 
in doubt, use &quot;$umask 0000&quot; right at the beginning of the configuration file to 
remove any restrictions.</p>
<p>$FileCreateMode may be specified multiple times. If so, it specifies the 
creation mode for all selector lines that follow until the next $FileCreateMode 
directive. Order of lines is vitally important. Here is a sample (this is deemed 
to be a complete rsyslog.conf):</p>
<p><code><b>$umask 0000 # make sure nothing interfers with the following 
definitions<br>
*.* /var/log/file-with-0644-default<br>
$FileCreateMode 0600<br>
*.* /var/log/file-with-0600<br>
$FileCreateMode 0644<br>
*.* /var/log/file-with-0644</b></code></p>
<p>As you can see, open modes depend on position in the config file. Note the 
first line, which is created with the hardcoded default creation mode.</p>
<h2>DynaFileCacheSize</h2>
<p>This directive specifies the maximum size of the cache for 
dynamically-generated file names. Selector lines with dynamic files names ('?' 
indicator) support writing to multiple files with a single selector line. This 
setting specifies how many open file handles should be cached. If, for example, 
the file name is generated with the hostname in it and you have 100 different 
hosts, a cache size of 100 would ensure that files are opened once and then stay 
open. This can be a great way to increase performance. If the cache size is 
lower than the number of different files, the least recently used one is 
discarded (and the file closed). The hardcoded maximum is 10,000 - a value that 
we assume should already be very extreme. Please note that if you expect to run 
with a very large number of files, you probably need to reconfigure the kernel 
to support such a large number. In practice, we do NOT recommend to use a cache 
of more than 1,000 entries. The cache lookup would probably require more time 
than the open and close operations. The minimum value is 1. Here is a sample:</p>
<p><code><b>$DynaFileCacheSize 100&nbsp;&nbsp;&nbsp; # a cache of 100 files at 
most</b></code></p>
<p>Numbers are always in decimal. Leading zeros should be avoided (in some later 
version, they may be mis-interpreted as being octal). Multiple directives may be 
given. They are applied to selector lines based on order of appearance.</p>
<h2>Templates</h2>
<p>Templates are a key feature of rsyslog. They allow to specify any format a user 
might want. They are also used for dynamic file name generation. 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 &quot;template_&quot; 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,&quot;\7Text %property% some more text\n&quot;,&lt;options&gt;</code></blockquote>
<p>The &quot;$template&quot; is the template directive. It tells rsyslog that this line 
contains a template. &quot;MyTemplateName&quot; 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 &quot;cool&quot; 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 &lt;options&gt; 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 in MySQL format. This will 
replace single quotes (&quot;'&quot;) and the backslash character by their 
backslash-escaped counterpart (&quot;\'&quot; and &quot;\\&quot;) inside each field. Please note 
that in MySQL configuration, the <code class="literal">NO_BACKSLASH_ESCAPES</code> 
mode must be turned off for this format to work (this is the default).</p>
<p><b>stdsql</b> - format the string suitable for a SQL statement that is to be 
sent to a standards-compliant sql server. This will 
replace single quotes (&quot;'&quot;) by two single quotes (&quot;''&quot;) inside each field. 
You must use stdsql together with MySQL if in MySQL configuration the
<code class="literal">NO_BACKSLASH_ESCAPES</code> is turned on.</p>
<p>Either the <b>sql</b> or <b>stdsql</b>&nbsp; 
option <b>must</b> be specified when a template is used for writing to a database, 
otherwise injection might occur. Please note that due to the unfortunate fact 
that several vendors have violated the sql standard and introduced their own 
escape methods, it is impossible to have a single option doing all the work.&nbsp; 
So you yourself must make sure you are using the right format. <b>If you choose 
the wrong one, you are still vulnerable to sql injection.</b><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 ;)</p>
<p>The default template for the write to database action has the sql option set. 
As we currently support only MySQL and the sql option matches the default MySQL 
configuration, this is a good choice. However, if you have turned on
<code class="literal">NO_BACKSLASH_ESCAPES</code> in your MySQL config, you need 
to supply a template with the stdsql option. Otherwise you will become 
vulnerable to SQL injection. <br>
<br>
To escape:<br>
% = \%<br>
\ = \\ --&gt; '\' is used to escape (as in C)<br>
$template TraditionalFormat,%timegenerated% %HOSTNAME% %syslogtag%%msg%\n&quot;<br>
<br>
Properties can be accessed by the <a href="property_replacer.html">property replacer</a> 
(see there for details).</p>
<p><b>Please note that as of 1.15.0, templates can also by used to generate 
selector lines with dynamic file names.</b> For example, if you would like to 
split syslog messages from different hosts to different files (one per host), 
you can define the following template:</p>
<blockquote><code>$template DynFile,&quot;/var/log/system-%HOSTNAME%.log&quot;</code></blockquote>
<p>This template can then be used when defining an output selector line. It will 
result in something like &quot;/var/log/system-localhost.log&quot;</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 &quot;file&quot; 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 &quot;name&quot;. 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>Filter Conditions</h2>
<p>Rsyslog offers two different types &quot;filter conditions&quot;:</p>
<ul>
	<li>&quot;traditional&quot; severity and facility based selectors</li>
	<li>property-based filters</li>
</ul>
<h3>Blocks</h3>
<p>Rsyslogd supports BSD-style blocks inside rsyslog.conf. Each block of lines 
is separated from the previous block by a program or hostname specification. A 
block will only log messages corresponding to the most recent program and 
hostname specifications given. Thus, a block which selects ‘ppp’ as the program, 
directly followed by a block that selects messages from the hostname ‘dialhost’, 
then the second block will only log messages from the ppp program on dialhost.
</p>
<p>A program specification is a line beginning with ‘!prog’ and the following 
blocks will be associated with calls to syslog from that specific program. A 
program specification for ‘foo’ will also match any message logged by the kernel 
with the prefix ‘foo: ’. A hostname specification of the form ‘+hostname’ and 
the following blocks will be applied to messages received from the specified 
hostname. Alternatively, a hostname specification ‘-hostname’ causes the 
following blocks to be applied to messages from any host but the one specified. 
If the hostname is given as ‘@’, the local hostname will be used. (NOT YET 
IMPLEMENTED) A program or hostname specification may be reset by giving the 
program or hostname as ‘*’.</p>
<p>Please note that the &quot;#!prog&quot;, &quot;#+hostname&quot; and &quot;#-hostname&quot; syntax available 
in BSD syslogd is not supported by rsyslogd. By default, no hostname or program 
is set.</p>
<h3>Selectors</h3>
<p><b>Selectors are the traditional way of filtering syslog messages.</b> They 
have been kept in rsyslog with their orginal syntax, because it is well-known, 
highly effective and also needed for compatibility with stock syslogd 
configuration files. If you just need to filter based on priority and facility, 
you should do this with selector lines. They are <b>not</b> second-class 
citicens in rsyslog and offer the best performance for this job.</p>
<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. Rsyslogd 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 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>
<h3>Property-Based Filters</h3>
<p>Property-based filters are unique to rsyslogd. They allow to filter on any 
property, like HOSTNAME, syslogtag and msg. A list of all currently-supported 
properties can be found in the <a href="property_replacer.html">property 
replacer documentation</a> (but keep in mind that only the properties, not the 
replacer is supported). With this filter, each properties can be checked against 
a specified value, using a specified compare operation. Currently, there is only 
a single compare operation (contains) available, but additional operations will be added in the 
future.</p>
<p>A property-based filter must start with a colon in column 0. This tells 
rsyslogd that it is the new filter type. The colon must be followed by the 
property name, a comma, the name of the compare operation to carry out, another 
comma and then the value to compare against. This value must be quoted. There 
can be spaces and tabs between the commas. Property names and compare operations 
are case-sensitive, so &quot;msg&quot; works, while &quot;MSG&quot; is an invalid property name. In 
brief, the syntax is as follows:</p>
<p><code><b>:property, [!]compare-operation, &quot;value&quot;</b></code></p>
<p>The following <b>compare-operations</b> are currently supported:</p>
<table border="1" width="100%" id="table1">
	<tr>
		<td>contains</td>
		<td>Checks if the string provided in value is contained in the property. 
		There must be an exact match, wildcards are not supported.</td>
	</tr>
	<tr>
		<td>isequal</td>
		<td>Compares the &quot;value&quot; string provided and the property contents. 
		These two values must be exactly equal to match. The difference to 
		contains is that contains searchs for the value anywhere inside the 
		property value, whereas all characters must be identical for isequal. As 
		such, isequal is most useful for fields like syslogtag or FROMHOST, 
		where you probably know the exact contents.</td>
	</tr>
	<tr>
		<td>startswith</td>
		<td>Checks if the value is found exactly at the beginning of the 
		property value. For example, if you search for &quot;val&quot; with<p><code><b>:msg, 
		startswith, &quot;val&quot;</b></code></p>
		<p>it will be a match if msg contains &quot;values are in this message&quot; but 
		it won't match if the msg contains &quot;There are values in this message&quot; 
		(in the later case, contains would match). Please note that &quot;startswith&quot; 
		is by far faster than regular expressions. So even once they are 
		implemented, it can make very much sense (performance-wise) to use &quot;startswith&quot;.</td>
	</tr>
	<tr>
		<td>regex</td>
		<td><b>NOT YET IMPLEMENTED</b> - value holds an regular expression</td>
	</tr>
</table>
<p>You can use the bang-character (!) immediately in front of a 
compare-operation, the outcome of this operation is negated. For example, if msg 
contains &quot;This is an informative message&quot;, the following sample would not match:</p>
<p><code><b>:msg, contains, &quot;error&quot;</b></code></p>
<p>but this one matches:</p>
<p><code><b>:msg, !contains, &quot;error&quot;</b></code></p>
<p>Using negation can be useful if you would like to do some generic processing 
but exclude some specific events. You can use the discard action in conjunction 
with that. A sample would be:</p>
<p><code><b>*.* /var/log/allmsgs-including-informational.log<br>
:msg, contains, &quot;informational&quot;&nbsp; <font color="#FF0000" size="4">~</font>
<br>*.* /var/log/allmsgs-but-informational.log</b></code></p>
<p>Do not overlook the red tilde in line 2! In this sample, all messages are 
written to the file allmsgs-including-informational.log. Then, all messages 
containing the string &quot;informational&quot; are discarded. That means the config file 
lines below the &quot;discard line&quot; (number 2 in our sample) will not be applied to 
this message. Then, all remaining lines will also be written to the file 
allmsgs-but-informational.log.</p>
<p><b>Value</b> is a quoted string. It supports some escape sequences:</p>
<p>\&quot; - the quote character (e.g. &quot;String with \&quot;Quotes\&quot;&quot;)<br>
\\ - the backslash character (e.g. &quot;C:\\tmp&quot;)</p>
<p>Escape sequences always start with a backslash. Additional escape sequences 
might be added in the future. Backslash characters <b>must</b> be escaped. Any 
other sequence then those outlined above is invalid and may lead to 
unpredictable results.</p>
<p>Probably, &quot;msg&quot; is the most prominent use case of property based filters. It 
is the actual message text. If you would like to filter based on some message 
content (e.g. the presence of a specific code), this can be done easily by:</p>
<p><code><b>:msg, contains, &quot;ID-4711&quot;</b></code></p>
<p>This filter will match when the message contains the string &quot;ID-4711&quot;. Please 
note that the comparison is case-sensitive, so it would not match if &quot;id-4711&quot; 
would be contained in the message.</p>
<p>Getting property-based filters right can sometimes be challenging. In order 
to help you do it with as minimal effort as possible, rsyslogd spits out debug 
information for all property-based filters during their evaluation. To enable 
this, run rsyslogd in foreground and specify the &quot;-d&quot; option.</p>
<p>Boolean operations inside property based filters (like 'message contains 
&quot;ID17&quot; or message contains &quot;ID18&quot;') are currently not supported 
(except for &quot;not&quot; as outlined above). Please note 
that while it is possible to query facility and severity via property-based filters, 
it is far more advisable to use classic selectors (see above) for those 
cases.</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 &quot;logfile&quot;. 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 &quot;/''.<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
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
syncing by specifying the &quot;-&quot; in front of the file name. </p>
<p><b>The filename can be either static </b>(always the same) or <b>dynamic</b> 
(different based on message received). The later is useful if you would 
automatically split messages into different files based on some message 
criteria. For example, dynamic file name selectors allow you to split messages 
into different files based on the host that sent them. With dynamic file names, 
everything is automatic and you do not need any filters. </p>
<p>It works via the template system. First, you define a template for the file 
name. An example can be seen above in the description of template. We will use 
the &quot;DynFile&quot; template defined there. Dynamic filenames are indicated by 
specifying a questions mark &quot;?&quot; instead of a slash, followed by the template 
name. Thus, the selector line for our dynamic file name would look as follows:</p>
<p align="center">
<code>*.* ?DynFile</code>
</p>
<p>That's all you need to do. Rsyslog will now automatically generate file names 
for you and store the right messages into the right files. Please note that the 
minus sign also works with dynamic file name selectors. Thus, to avoid syncing, 
you may use</p>
<p align="center">
<code>*.* -?DynFile</code></p>
<p>And of course you can use templates to specify the output format:</p>
<p align="center">
<code>*.* ?DynFile;MyTemplate</code></p>
<p><b>A word of caution:</b> rsyslog creates files as needed. So if a new host 
is using your syslog server, rsyslog will automatically create a new file for 
it. <b>However, directories are never created</b>. So if you use a dynamic 
directory name, you must make sure that all possible directories are created, 
otherwise the writes will fail. This restriction will most probably be removed 
in later versions of rsyslogd.</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. 
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>
<b>Please note that this version of rsyslogd by default does NOT forward messages 
it has received from the network to another host. Specify the &quot;-h&quot; option to enable this.</b></p>
<p>To forward messages to another host, prepend the hostname with the at sign (&quot;@&quot;).&nbsp; 
A single at sign means that messages will be forwarded via UDP protocol (the 
standard for syslog). If you prepend two at signs (&quot;@@&quot;), the messages will be 
transmitted via TCP. Please note that plain TCP based syslog is not officially 
standardized, but most major syslogds support it (e.g. syslog-ng or WinSyslog). 
The forwarding action indicator (at-sign) can be followed by one or more options. 
If they are given, they must be immediately (without a space) following the 
final at sign and be enclosed in parenthesis. The individual options must be 
separated by commas. The following options are right now defined:</p>
<table border="1" width="100%" id="table2">
	<tr>
		<td>
		<p align="center"><b>z&lt;number&gt;</b></td>
		<td>Enable zlib-compression for the message. The &lt;number&gt; is the 
		compression level. It can be 1 (lowest gain, lowest CPU overhead) to 9 (maximum 
		compression, highest CPU overhead). The level can also be 0, which means 
		&quot;no compression&quot;. If given, the &quot;z&quot; option is ignored. So this does not 
		make an awful lot of sense. There is hardly a difference between level 1 
		and 9 for typical syslog messages. You can expect a compression gain 
		between 0% and 30% for typical messages. Very chatty messages may 
		compress up to 50%, but this is seldomly seen with typicaly traffic. 
		Please note that rsyslogd checks the compression gain. Messages with 60 
		bytes or less will never be compressed. This is because compression gain 
		is pretty unlikely and we prefer to save CPU cycles. Messags over that 
		size are always compressed. However, it is checked if there is a gain in 
		compression and only if there is, the compressed message is transmitted. 
		Otherwise, the uncompressed messages is transmitted. This saves the 
		receiver CPU cycles for decompression. It also prevents small message to 
		actually become larger in compressed form.<p><b>Please note that when a 
		TCP transport is used, compression will also turn on 
		syslog-transport-tls framing. See the &quot;o&quot; option for important 
		information on the implications.</b></p>
		<p>Compressed messages are automatically detected and decompressed by 
		the receiver. There is nothing that needs to be configured on the 
		receiver side.</td>
	</tr>
	<tr>
		<td>
		<p align="center"><b>o</b></td>
		<td><b>This option is experimental. Use at your own risk and only if you 
		know why you need it! If in doubt, do NOT turn it on.</b><p>This option 
		is only valid for plain TCP based transports. It selects a different 
		framing based on IETF internet draft syslog-transport-tls-06. This 
		framing offers some benefits over traditional LF-based framing. However, 
		the standardization effort is not yet complete. There may be changes in 
		upcoming versions of this standard. Rsyslog will be kept in line with 
		the standard. There is some chance that upcoming changes will be 
		incompatible to the current specification. In this case, all systems 
		using -transport-tls framing must be upgraded. There will be no effort 
		made to retain compatibility between different versions of rsyslog. The 
		primary reason for that is that it seems technically impossible to 
		provide compatibility between some of those changes. So you should take 
		this note very serious. It is not something we do not *like* to do (and 
		may change our mind if enough pepole beg...), it is something we most 
		probably *can not* do for technical reasons (aka: you can beg as much as 
		you like, it won't change anything...).</p>
		<p>The most important implication is that compressed syslog messages via 
		TCP must be considered with care. Unfortunately, it is technically 
		impossible to transfer compressed records over traditional syslog plain 
		tcp transports, so you are left with two evil choices...</td>
	</tr>
</table>
<p><br>
The hostname may be followed by a colon and the destination port.</p>
<p>The following is an example selector line with forwarding:</p>
<p>*.*&nbsp;&nbsp;&nbsp; @@(o,z9)192.168.0.1:1470</p>
<p>In this example, messages are forwarded via plain TCP with experimental 
framing and maximum compression to the host 192.168.0.1 at port 1470.</p>
<p>*.* @192.168.0.1</p>
<p>In the example above, messages are forwarded via UDP to the machine 
192.168.0.1, the destination port defaults to 514. Messages will not be 
compressed.</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 (&quot;,''). 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 (&quot;*'').</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 (&quot;&gt;&quot;) 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>
&gt;dbhost,dbname,dbuser,dbpassword;dbtemplate</p>
<h3>Discard</h3>
<p>If the discard action is carried out, the received message is immediately 
discarded. No further processing of it occurs. Discard has primarily been added 
to filter out messages before carrying on any further processing. For obvious 
reasons, the results of &quot;discard&quot; are depending on where in the configuration 
file it is being used. Please note that once a message has been discarded there 
is no way to retrive it in later configuration file lines.</p>
<p>Discard can be highly effective if you want to filter out some annoying 
messages that otherwise would fill your log files. To do that, place the discard 
actions early in your log files. This often plays well with property-based 
filters, giving you great freedom in specifying what you do not want.</p>
<p>Discard is just the single tilde character with no further parameters:</p>
<p>~</p>
<p>For example,</p>
<p>*.*&nbsp;&nbsp; ~</p>
<p>discards everything (ok, you can achive the same by not running rsyslogd at 
all...).</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 &quot;mychannel&quot; to the action, use &quot;$mychannel&quot;. 
Output channels support template definitions like all all other actions.</p>
<h3>Shell Execute</h3>
<p>This executes a program in a subshell. The programm is passed the 
template-generated message as the only command line parameter. Rsyslog waits 
until the program terminates and only then continues to run.</p>
<p>^programm-to-execute;template</p>
<p>The program-to-execute can be any valid executable.</p>
<p><b>WARNING:</b> The Shell Execute action was added to serve an urgent need. 
While it is considered reasonable save when used with some thinking, its 
implications must be considered. The current implementation uses a system() call 
to execute the command. This is not the best way to do it (and will hopefully 
changed in further releases). Also, proper escaping of special characters is 
done to prevent command injection. However, attackers always find smart ways to 
circumvent escaping, so we can not say if the escaping applied will really safe 
you from all hassles. Lastely, rsyslog will wait until the shell command 
terminates. Thus, a program error in it (e.g. an infinite loop) can actually 
disable rsyslog. Even without that, during the programs run-time no messages are 
processed by rsyslog. As the IP stacks buffers are quickly overflowed, this 
bears an increased risk of message loss. You must be aware of these implications. 
Even though they are severe, there are several cases where the &quot;shell execute&quot; 
action is very useful. This is the reason why we have included it in its current 
form. To mitigate its risks, always a) test your program thouroughly, b) make 
sure its runtime is as short as possible (if it requires a longer run-time, you 
might want to spawn your own sub-shell asynchronously), c) apply proper 
firewalling so that only known senders can send syslog messages to rsyslog. 
Point c) is especially important: if rsyslog is accepting message from any hosts, 
chances are much higher that an attacker might try to exploit the &quot;shell execute&quot; 
action.</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 &quot;TEMPLATES&quot; 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,&quot;%timegenerated% %HOSTNAME%<br>
%syslogtag%%msg:::drop-last-lf%\n&quot;<br>
<br>
A template that tells you a little more about the message:<br>
$template precise,&quot;%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,<br>
%syslogtag%,%msg%\n&quot;<br>
<br>
A template for RFC 3164 format:<br>
$template RFC3164fmt,&quot;&lt;%PRI%&gt;%TIMESTAMP% %HOSTNAME% %syslogtag%%msg%&quot;<br>
<br>
A template for the format traditonally used for user messages:<br>
$template usermsg,&quot; XXXX%syslogtag%%msg%\n\r&quot;<br>
<br>
And a template with the traditonal wall-message format:<br>
$template wallmsg,&quot;\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,&quot;insert iut, message, receivedat values<br>
('%iut%', '%msg:::UPPERCASE%', '%timegenerated:::date-mysql%')<br>
into systemevents\r\n&quot;, 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,&quot;%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&quot;</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>
*.* &gt;dbhost,dbname,dbuser,dbpassword;dbtemplate<br>
<br>
This rule writes all message to the database &quot;dbname&quot; hosted on &quot;dbhost&quot;. The 
login is done with user &quot;dbuser&quot; and password &quot;dbpassword&quot;. The actual table 
that is updated is specified within the template (which contains the insert 
statement). The template is called &quot;dbtemplate&quot; in this case.</p>
<p>:msg,contains,&quot;error&quot; @errorServer</p>
<p>This rule forwards all messages that contain the word &quot;error&quot; in the msg part 
to the server &quot;errorServer&quot;. Forwarding is via UDP. Please note the colon in 
fron</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>
&nbsp;</p>
</body>
</html>