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
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
|
<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 "normal" 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 ("#'') and empty lines are ignored.
<h2>ActionExecOnlyIfPreviousIsSuspended</h2>
<p>This directive allows to specify if actions should always be executed ("off,"
the default) or only if the previous action is suspended ("on"). This directive
works hand-in-hand with the multiple actions per selector feature. It can be
used, for example, to create rules that automatically switch destination servers
or databases to a (set of) backup(s), if the primary server fails. Note that
this feature depends on proper implementation of the suspend feature in the
output module.</p>
<p>The following is an example of what can be done with it (a config file
excerpt):</p>
<p><code><b>*.* @@primary-syslog.example.com<br>
$ActionExecOnlyIfPreviousIsSuspended on<br>
& @@secondary-1-syslog.example.com # & is used to
have more than one action for<br>
& @@secondary-2-syslog.example.com # the same
selector - the mult-action feature<br>
& /var/log/localbuffer<br>
$ActionExecOnlyIfPreviousIsSuspended off # to re-set it for the next selector</b></code></p>
<p>This selector processes all messages it receives (*.*). It tries to
forward every message to primary-syslog.example.com (via tcp). If it can not
reach that server, it tries secondary-1-syslog.example.com, if that fails too,
it tries secondary-2-syslog.example.com. If neither of these servers can be
connected, the data is stored in /var/log/localbuffer. Please note that the
secondaries and the local log buffer are only used if the one before them does
not work. So ideally, /var/log/localbuffer will never receive a message. If one
of the servers resumes operation, it automatically takes over processing again.</p>
<p>We strongly advise not to use repeated line reduction together with
ActionExecOnlyIfPreviousIsSuspended. It may lead to "interesting" and undesired
results (but you can try it if you like). </p>
<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
"-w" 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 <protocol>, ip[/bits], ip[/bits]</b></code></p>
<p>"$AllowedSender" is the directive - it must be written exactly as shown and
the $ must start at the first column of the line. "<protocol>" is either "UDP"
or "TCP". It must immediately be followed by the comma, else you will receive an
error message. "ip[/bits]" is a machine or network ip address as in
"192.0.2.0/24" or "127.0.0.1". If the "/bits" part is omitted, a single host is
assumed (32 bits or mask 255.255.255.255). "/0" 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 with IPv4, they are adjusted to 32.
For IPv6, the limit is 128 for obvious reasons. Hostnames, with and without
wildcards, may also be provided. If so, the result of revers DNS resolution is
used for filtering.
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 malicious person could spoof the
address
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>Rsyslog also detects some kind of malicious reverse DNS entries. In any case,
using DNS names adds an extra layer of vulnerability. We recommend to stick with
hard-coded IP addresses whereever possible.</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, [::1]/128,
*.example.net, somehost.example.com</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 "$umask 0000" 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>DebugPrintCFSyslineHandlerList</h2>
<p>Specifies whether or not the configuration file sysline handler list should be written to the debug
log. Possible values: on/off. Default is on. Does not affect operation if debugging is
disabled.</p>
<h2>DebugPrintModuleList</h2>
<p>Specifies whether or not the module list should be written to the debug
log. Possible values: on/off. Default is on. Does not affect operation if debugging is
disabled.</p>
<h2>DebugPrintTemplateList</h2>
<p>Specifies whether or not the template list should be written to the debug
log. Possible values: on/off. Default is on. Does not affect operation if debugging is
disabled.</p>
<h2>DirCreateMode</h2>
<p>This is the same as $FileCreateMode, but for directories automatically
generated.</p>
<h2>DirGroup</h2>
<p>Set the group for directories newly created. Please note that this setting
does not affect the group of directories already existing. The parameter is a
group name, for which the groupid is obtained by rsyslogd on startup and on
HUPing. Interim changes to the user mapping are not detected.</p>
<p><code><b>$DirGroup loggroup</b></code></p>
<h2>DirOwner</h2>
<p>Set the file owner for directories newly created. Please note that this
setting does not affect the owner of directories already existing. The parameter
is a user name, for which the userid is obtained by rsyslogd on startup and on
HUPing. Interim changes to the user mapping are not detected.</p>
<p><code><b>$DirOwner loguser</b></code></p>
<h2>IncludeConfig</h2>
<p>This directive allows to include other files into the main configuration
file. As soon as an IncludeConfig directive is found, the contents of the new
file is processed. IncludeConfigs can be nested. Please note that from a logical
point of view the files are merged. Thus, if the include modifies some
parameters (e.g. $DynaFileChacheSize), these new parameters are in place for the
"calling" configuration file when the include is completed. To avoid any side
effects, do a $ResetConfigVariables after the $IncludeConfig. It may also be a
good idea to do a $ResetConfigVariables right at the start of the include, so
that the module knows exactly what it does. Of course, one might specifically
NOT do this to inherit parameters from the main file. As always, use it as it
best fits...</p>
<p><code><b>$IncludeConfig /etc/some-included-file.conf</b></code></p>
<p>Directories can also be included. To do so, the name must end on a slash:</p>
<p><code><b>$IncludeConfig /etc/rsyslog.d/</b></code></p>
<p>In this case, all regular files in the /etc/rsyslog.d directory are included.
Files starting with "." are ignored - so you can use them to place comments into
the dir (e.g. "/etc/rsyslog.d/.mycomment" will be ignored).
<a href="http://sourceforge.net/tracker/index.php?func=detail&aid=1764088&group_id=123448&atid=696555">
Michael Biebl had the idea to this functionality</a>. Let me quote hím: </p>
<blockquote>
<p><i>Say you can add an option<br>
$IncludeConfig /etc/rsyslog.d/<br>
(which probably would make a good default)<br>
to /etc/rsyslog.conf, which would then merge and include all *.conf files<br>
in /etc/rsyslog.d/.<br>
<br>
This way, a distribution can modify its packages easily to drop a simple<br>
config file into this directory upon installation.<br>
<br>
As an example, the network-manager package could install a simple config<br>
file /etc/rsyslog.d/network-manager.conf which would contain.<br>
:programname, contains, "NetworkManager" -/var/log/NetworkManager.log<br>
<br>
Upon uninstallation, the file could be easily removed again. This approach<br>
would be much cleaner and less error prone, than having to munge around<br>
with the /etc/rsyslog.conf file directly.</i></p>
</blockquote>
<p>Please note that in this description, only "*.conf" files would be read. The
actual implementation, however, reads all files except for those starting with a
dot. If you find this is a real big problem, please complain.</p>
<h2>RepeatedMsgReduction</h2>
<p>This directive specifies whether or not repeated messages should be reduced
(this is the "Last line repeated n times" feature). If set to on, repeated messages are reduced. If set to off, every
message is logged. Please note that
this directive overrides the -e command line option. In case -e is given, it is
just the default value until the first RepeatedMsgReduction directive is
encountered. Sample:</p>
<p><code><b>$RepeatedMsgReduction off # log every message</b></code></p>
<p>Directives affects selector lines until a new directive is specified.</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 # 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>DropMsgsWithMaliciousDnsPTRRecords</h2>
<p>Rsyslog contains code to detect malicious DNS PTR records (reverse name
resolution). An attacker might use specially-crafted DNS entries to make you
think that a message might have originated on another IP address. Rsyslog can
detect those cases. It will log an error message in any case. It this option
here is set to "on", the malicious message will be completely dropped from your
logs. If the option is set to "off", the message will be logged, but the
original IP will be used instead of the DNS name.</p>
<p><code><b>$DropMsgsWithMaliciousDnsPTRRecords on</b></code></p>
<h2>DropTrailingLFOnReception</h2>
<p>Syslog messages frequently have the line feed character (LF) as the last
character of the message. In allmost all cases, this LF should not really become
part of the message. However, recent IETF syslog standardization recommends
against modifying syslog messages (e.g. to keep digital signatures valid). This
option allows to specify if trailing LFs should be dropped or not. The default
is to drop them, which is consistent with what sysklogd does. To not drop them,
use</p>
<p><code><b>$DropTrailingLFOnRecption off</b></code></p>
<h2>ControlCharacterEscapePrefix</h2>
<p>This option specifies the prefix character to be used for control character
escaping (see option $EscapeControlCharactersOnReceive). By default, it is '\',
which is backwards-compatible with sysklogd. Change it to '#' in order to be
compliant to the value that is somewhat suggested by Internet-Draft
syslog-protocol. The first non-whitespace character after the command is treated
as prefix:</p>
<p><code><b>$EscapeControlCharactersOnReceive # # as of syslog-protocol</b></code></p>
<p><b>IMPORTANT</b>: do not use the ' character. This is reserved and will most
probably be used in the future as a character delimiter. For the same reason,
the syntax of this directive will probably change in furture releases.</p>
<h2>EscapeControlCharactersOnReceive</h2>
<p>This directive instructs rsyslogd to replace control characters during
reception of the message. The intent is to provide a way to stop non-printable
messages from entering the syslog system as whole. If this option is truned on,
all control-characters are converted to a 3-digit octal number and be prefixed
with the $ControlCharacterEscapePrefix character (being '\' by default). For
example, if the BEL character (ctrl-g) is included in the message, it would be
converted to "\007". To be compatible to sysklogd, this option must be turned
on.</p>
<p><code><b>$EscapeControlCharactersOnReceive on</b></code></p>
<p><b>Warning:</b></p>
<ul>
<li>turning on this option most probably destroys non-western character sets
(like Japanese, Chinese and Korean)</li>
<li>turning on this option destroys digital signatures if such exists inside
the message</li>
</ul>
<h2>FailOnChownFailure</h2>
<p>This option modifies behaviour of dynaFile creation. If different owners or
groups are specified for new files or directories and rsyslogd fails to set
these new owners or groups, it will log an error and NOT write to the file in
question if that option is set to "on". If it is set to "off", the error will be
ignored and processing continues. Keep in mind, that the files in this case may
be (in)accessible by people who should not have permission. The default is "on".</p>
<p><code><b>$FailOnChownFailure off</b></code></p>
<h2>FileGroup</h2>
<p>Set the group for dynaFiles newly created. Please note that this setting does
not affect the group of files already existing. The parameter is a group name,
for which the groupid is obtained by rsyslogd on startup and on HUPing. Interim
changes to the user mapping are not detected.</p>
<p><code><b>$FileGroup loggroup</b></code></p>
<h2>FileOwner</h2>
<p>Set the file owner for dynaFiles newly created. Please note that this setting
does not affect the owner of files already existing. The parameter is a user
name, for which the userid is obtained by rsyslogd on startup and on HUPing.
Interim changes to the user mapping are not detected.</p>
<p><code><b>$FileOwner loguser</b></code></p>
<h2>ResetConfigVariables</h2>
<p>Resets all configuration variables to their default value. Any settings made
will not be applied to configuration lines following the $ResetConfigVariables.
This is a good method to make sure no side-effects exists from previous
directives. This directive has no parameters.</p>
<p><code><b>$ResetConfigVariables</b></code></p>
<h2>ModLoad</h2>
<p>This currently is a dummy directive. It will support the loading of plug-ins
in future releases of rsyslog supporting plug-ins. Currently, only</p>
<p><code><b>$ModLoad MySQL</b></code></p>
<p>is supported, which activates MySQL support (if rsyslog is compiled with
MySQL functionality).</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 "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 in MySQL format. This will
replace single quotes ("'") and the backslash character by their
backslash-escaped counterpart ("\'" and "\\") 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 ("'") by two single quotes ("''") 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>
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.
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>
\ = \\ --> '\' 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>
<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,"/var/log/system-%HOSTNAME%.log"</code></blockquote>
<p>This template can then be used when defining an output selector line. It will
result in something like "/var/log/system-localhost.log"</p>
<h2>Output Channels</h2>
<p>Output Channels are a new concept first introduced in rsyslog 0.9.0. <b>As of this
writing, it is most likely that they will be replaced by something different in
the future.</b> 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. This command always has
exactly one parameter. The binary is that part of action-on-max-size before the
first space, its parameter is everything behind that space.<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>
<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 "filter conditions":</p>
<ul>
<li>"traditional" 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 "#!prog", "#+hostname" and "#-hostname" 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 "msg" works, while "MSG" is an invalid property name. In
brief, the syntax is as follows:</p>
<p><code><b>:property, [!]compare-operation, "value"</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 "value" 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 "val" with<p><code><b>:msg,
startswith, "val"</b></code></p>
<p>it will be a match if msg contains "values are in this message" but
it won't match if the msg contains "There are values in this message"
(in the later case, contains would match). Please note that "startswith"
is by far faster than regular expressions. So even once they are
|
