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
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<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. This may be changed by a command line option.</p>
<p><a href="http://wiki.rsyslog.com/index.php/Configuration_Samples">
Configuration file examples can be found in the rsyslog wiki</a>.</p>
<p>There is also one sample file provided together with the
documentation set. If you do not like to read, be sure to have at least
a quick look at
<a href="rsyslog-example.conf">rsyslog-example.conf</a>.
</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>Modules</h2>
<p>Rsyslog has a modular design. Consequently, there is a growing
number of modules. Here is the entry point to their documentation and
what they do (list is currently not complete)</p>
<ul>
<li><a href="omsnmp.html">omsnmp</a> - SNMP
trap output module</li>
<li><a href="omrelp.html">omrelp</a> - RELP
output module</li>
<li>omgss - output module for GSS-enabled syslog</li>
<li>ommysql - output module for MySQL</li>
<li>ompgsql - output module for PostgreSQL</li>
<li><a href="omlibdbi.html">omlibdbi</a> -
generic database output module (Firebird/Interbase, MS SQL, Sybase,
SQLLite, Ingres, Oracle, mSQL)</li>
<li><a href="ommail.html">ommail</a> -
permits rsyslog to alert folks by mail if something important happens</li>
<li><a href="imfile.html">imfile</a>
- input module for text files</li>
<li><a href="imrelp.html">imrelp</a> - RELP
input module</li>
<li>imudp - udp syslog message input</li>
<li><a href="imtcp.html">imtcp</a> - input
plugin for plain tcp syslog</li>
<li><a href="imgssapi.html">imgssapi</a> -
input plugin for plain tcp and GSS-enable syslog</li>
<li>immark - support for mark messages</li>
<li><a href="imklog.html">imklog</a> - kernel logging</li>
<li><a href="imuxsock.html">imuxsock</a> -
unix sockets, including the system log socket</li>
<li><a href="im3195.html">im3195</a> -
accepts syslog messages via RFC 3195</li>
</ul>
<p>Please note that each module provides configuration
directives, which are NOT necessarily being listed below. Also
remember, that a modules configuration directive (and functionality) is
only available if it has been loaded (using $ModLoad).</p>
<h2>Lines</h2>
Lines can be continued by specifying a backslash ("\") as the last
character of the line.<br>
<h2>Global Directives</h2>
<p>All global directives need to be specified on a line by their
own and must start with a dollar-sign. Here is a list in alphabetical
order. Follow links for a description.</p>
<p>Not all directives have an in-depth description right now.
Default values for them are in bold. A more in-depth description will
appear as implementation progresses. Directives may change during that
process, we will NOT try hard to maintain backwards compatibility
(after all, v3 is still very early in development and quite
unstable...). So you have been warned ;)</p>
<p><b>Be sure to read information about <a href="queues.html">queues in rsyslog</a></b> -
many parameter settings modify queue parameters. If in doubt, use the
default, it is usually well-chosen and applicable in most cases.</p>
<ul>
<li><a href="rsconf1_actionexeconlywhenpreviousissuspended.html">$ActionExecOnlyWhenPreviousIsSuspended</a></li>
<li>$ActionExecOnlyOnceEveryInterval <seconds> -
execute action only if the last execute is at last
<seconds> seconds in the past (more info in <a href="ommail.html">ommail</a>,
but may be used with any action)</li>
<li>$ActionFileDefaultTemplate [templateName] - sets a new
default template for file actions</li>
<li>$ActionFileEnableSync [on/<span style="font-weight: bold;">off</span>] - enables file
syncing capability of omfile</li>
<li>$ActionForwardDefaultTemplate [templateName] - sets a new
default template for UDP and plain TCP forwarding action</li>
<li>$ActionGSSForwardDefaultTemplate [templateName] - sets a
new default template for GSS-API forwarding action</li>
<li>$ActionQueueCheckpointInterval <number></li>
<li>$ActionQueueDequeueSlowdown <number> [number
is timeout in <i> micro</i>seconds (1000000us is 1sec!),
default 0 (no delay). Simple rate-limiting!]</li>
<li>$ActionQueueDiscardMark <number> [default
9750]</li>
<li>$ActionQueueDiscardSeverity <number>
[*numerical* severity! default 4 (warning)]</li>
<li>$ActionQueueFileName <name></li>
<li>$ActionQueueHighWaterMark <number> [default
8000]</li>
<li>$ActionQueueImmediateShutdown [on/<b>off</b>]</li>
<li>$ActionQueueSize <number></li>
<li>$ActionQueueLowWaterMark <number> [default
2000]</li>
<li>$ActionQueueMaxFileSize <size_nbr>, default 1m</li>
<li>$ActionQueueTimeoutActionCompletion <number>
[number is timeout in ms (1000ms is 1sec!), default 1000, 0 means
immediate!]</li>
<li>$ActionQueueTimeoutEnqueue <number> [number
is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]</li>
<li>$ActionQueueTimeoutShutdown <number> [number
is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]</li>
<li>$ActionQueueWorkerTimeoutThreadShutdown
<number> [number is timeout in ms (1000ms is 1sec!),
default 60000 (1 minute)]</li>
<li>$ActionQueueType [FixedArray/LinkedList/<b>Direct</b>/Disk]</li>
<li>$ActionQueueSaveOnShutdown [on/<b>off</b>]
</li>
<li>$ActionQueueWorkerThreads <number>, num worker threads, default 1, recommended 1</li>
<li>$ActionQueueWorkerThreadMinumumMessages <number>, default 100</li>
<li><a href="rsconf1_actionresumeinterval.html">$ActionResumeInterval</a></li>
<li>$ActionResumeRetryCount <number> [default 0, -1 means eternal]</li>
<li>$ActionSendResendLastMsgOnReconn <[on/<b>off</b>]> specifies if the last message is to be resend when a connecition broken and has been reconnedcted. May increase reliability, but comes at the risk of message duplication.
<li>$ActionSendStreamDriver <driver basename> just like $DefaultNetstreamDriver, but for the specific action
</li><li>$ActionSendStreamDriverMode <mode>, default 0, mode to use with the stream driver
(driver-specific)</li><li>$ActionSendStreamDriverAuthMode <mode>, authentication mode to use with the stream driver
(driver-specific)</li><li>$ActionSendStreamDriverPermittedPeer <ID>, accepted fingerprint (SHA1) or name of remote peer
(driver-specific) -<span style="font-weight: bold;"> directive may go away</span>!</li>
<li><a href="rsconf1_allowedsender.html">$AllowedSender</a></li>
<li><a href="rsconf1_controlcharacterescapeprefix.html">$ControlCharacterEscapePrefix</a></li>
<li><a href="rsconf1_debugprintcfsyslinehandlerlist.html">$DebugPrintCFSyslineHandlerList</a></li>
<li><a href="rsconf1_debugprintmodulelist.html">$DebugPrintModuleList</a></li>
<li><a href="rsconf1_debugprinttemplatelist.html">$DebugPrintTemplateList</a></li>
<li>$DefaultNetstreamDriver <drivername>, the default <a href="netstream.html">network stream driver</a> to use. Defaults to ptcp.$DefaultNetstreamDriverCAFile </path/to/cafile.pem></li>
<li>$DefaultNetstreamDriverCertFile </path/to/certfile.pem></li>
<li>$DefaultNetstreamDriverKeyFile </path/to/keyfile.pem></li>
<li><a href="rsconf1_dircreatemode.html">$DirCreateMode</a></li>
<li><a href="rsconf1_dirgroup.html">$DirGroup</a></li>
<li><a href="rsconf1_dirowner.html">$DirOwner</a></li>
<li><a href="rsconf1_dropmsgswithmaliciousdnsptrrecords.html">$DropMsgsWithMaliciousDnsPTRRecords</a></li>
<li><a href="rsconf1_droptrailinglfonreception.html">$DropTrailingLFOnReception</a></li>
<li><a href="rsconf1_dynafilecachesize.html">$DynaFileCacheSize</a></li>
<li><a href="rsconf1_escapecontrolcharactersonreceive.html">$EscapeControlCharactersOnReceive</a></li>
<li><a href="rsconf1_failonchownfailure.html">$FailOnChownFailure</a></li>
<li><a href="rsconf1_filecreatemode.html">$FileCreateMode</a></li>
<li><a href="rsconf1_filegroup.html">$FileGroup</a></li>
<li><a href="rsconf1_fileowner.html">$FileOwner</a></li>
<li><a href="rsconf1_gssforwardservicename.html">$GssForwardServiceName</a></li>
<li><a href="rsconf1_gsslistenservicename.html">$GssListenServiceName</a></li>
<li><a href="rsconf1_gssmode.html">$GssMode</a></li>
<li><a href="rsconf1_includeconfig.html">$IncludeConfig</a></li><li>MainMsgQueueCheckpointInterval <number></li>
<li>$MainMsgQueueDequeueSlowdown <number> [number
is timeout in <i> micro</i>seconds (1000000us is 1sec!),
default 0 (no delay). Simple rate-limiting!]</li>
<li>$MainMsgQueueDiscardMark <number> [default
9750]</li>
<li>$MainMsgQueueDiscardSeverity <severity>
[either a textual or numerical severity! default 4 (warning)]</li>
<li>$MainMsgQueueFileName <name></li>
<li>$MainMsgQueueHighWaterMark <number> [default
8000]</li>
<li>$MainMsgQueueImmediateShutdown [on/<b>off</b>]</li>
<li><a href="rsconf1_mainmsgqueuesize.html">$MainMsgQueueSize</a></li>
<li>$MainMsgQueueLowWaterMark <number> [default
2000]</li>
<li>$MainMsgQueueMaxFileSize <size_nbr>, default
1m</li>
<li>$MainMsgQueueTimeoutActionCompletion
<number> [number is timeout in ms (1000ms is 1sec!),
default
1000, 0 means immediate!]</li>
<li>$MainMsgQueueTimeoutEnqueue <number> [number
is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]</li>
<li>$MainMsgQueueTimeoutShutdown <number> [number
is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]</li>
<li>$MainMsgQueueWorkerTimeoutThreadShutdown
<number> [number is timeout in ms (1000ms is 1sec!),
default 60000 (1 minute)]</li>
<li>$MainMsgQueueType [<b>FixedArray</b>/LinkedList/Direct/Disk]</li>
<li>$MainMsgQueueSaveOnShutdown [on/<b>off</b>]
</li>
<li>$MainMsgQueueWorkerThreads <number>, num
worker threads, default 1, recommended 1</li>
<li>$MainMsgQueueWorkerThreadMinumumMessages
<number>, default 100</li>
<li><a href="rsconf1_markmessageperiod.html">$MarkMessagePeriod</a>
(immark)</li>
<li><a href="rsconf1_moddir.html">$ModDir</a></li>
<li><a href="rsconf1_modload.html">$ModLoad</a></li>
<li><a href="rsconf1_repeatedmsgreduction.html">$RepeatedMsgReduction</a></li>
<li><a href="rsconf1_resetconfigvariables.html">$ResetConfigVariables</a></li>
<li>$WorkDirectory <name> (directory for spool
and other work files)</li>
<li>$UDPServerAddress <IP> (imudp) -- local IP
address (or name) the UDP listens should bind to</li>
<li>$UDPServerRun <port> (imudp) -- former
-r<port> option, default 514, start UDP server on this
port, "*" means all addresses</li>
<li><a href="rsconf1_umask.html">$UMASK</a></li>
</ul>
<p><b>Where <size_nbr> is specified above,</b>
modifiers can be used after the number part. For example, 1k means
1024. Supported are k(ilo), m(ega), g(iga), t(era), p(eta) and e(xa).
Lower case letters refer to the traditional binary defintion (e.g. 1m
equals 1,048,576) whereas upper case letters refer to their new
1000-based definition (e.g 1M equals 1,000,000).</p>
<p>Numbers may include '.' and ',' for readability. So you can
for example specify either "1000" or "1,000" with the same result.
Please note that rsyslogd simply ignores the punctuation. Form it's
point of view, "1,,0.0.,.,0" also has the value 1000. </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>
<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>
<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.
</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>
<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 accidental 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 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>
<p>Template
names beginning with "RSYSLOG_" are reserved for rsyslog use. Do NOT
use them if, otherwise you may receive a conflict in the future (and
quite unpredictable behaviour). There is a small set of pre-defined
templates that you can use without the need to define it:</p>
<ul>
<li><span style="font-weight: bold;">RSYSLOG_TraditionalFileFormat</span>
- the "old style" default log file format with low-precision timestamps</li>
<li><span style="font-weight: bold;">RSYSLOG_FileFormat</span>
- a modern-style logfile format similar to TraditionalFileFormat, buth
with high-precision timestamps and timezone information</li>
<li><span style="font-weight: bold;">RSYSLOG_TraditionalForwardFormat</span>
- the traditional forwarding format with low-precision timestamps. Most
useful if you send messages to other syslogd's or rsyslogd
below
version 3.12.5.</li>
<li><span style="font-weight: bold;">RSYSLOG_ForwardFormat</span>
- a new high-precision forwarding format very similar to the
traditional one, but with high-precision timestamps and timezone
information. Recommended to be used when sending messages to rsyslog
3.12.5 or above.</li>
<li><span style="font-weight: bold;">RSYSLOG_SyslogProtocol23Format</span>
- the format specified in IETF's internet-draft
ietf-syslog-protocol-23, which is assumed to be come the new syslog
standard RFC. This format includes several improvements. The rsyslog
message parser understands this format, so you can use it together with
all relatively recent versions of rsyslog. Other syslogd's may get
hopelessly confused if receiving that format, so check before you use
it. Note that the format is unlikely to change when the final RFC comes
out, but this may happen.</li>
<li><span style="font-weight: bold;">RSYSLOG_DebugFormat</span>
- a special format used for troubleshooting property problems. This format
is meant to be written to a log file. Do <b>not</b> use for production or remote
forwarding.</li>
</ul>
<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 definition, 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 reached, rsyslogd will execute the action-on-max-size command
and then reopen the file and retry. The command should be something
like a <a href="log_rotation_fix_size.html">log rotation
script</a> 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 four different types "filter conditions":</p>
<ul>
<li>BSD-style blocks</li>
<li>"traditional" severity and facility based selectors</li>
<li>property-based filters</li>
<li>expression-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: ’. Alternatively, a
program specification ‘-foo’ causes the following blocks to be applied
to messages from any program but the one specified. 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 original
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 citizens
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 insensitive 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>
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 id="table1" border="1" width="100%">
<tbody>
<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 searches 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 implemented, it can make very much sense
(performance-wise) to use "startswith".</p>
</td>
</tr>
<tr>
<td>regex</td>
<td>Compares the property against the provided POSIX
regular
expression.</td>
</tr>
</tbody>
</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 "This is an informative message", the
following sample would not match:</p>
<p><code><b>:msg, contains, "error"</b></code></p>
<p>but this one matches:</p>
<p><code><b>:msg, !contains, "error"</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, "informational" <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 "informational" are discarded.
That means the config file lines below the "discard line" (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>\" - the quote character (e.g. "String with \"Quotes\"")<br>
\\ - the backslash character (e.g. "C:\\tmp")</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, "msg" 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, "ID-4711"</b></code></p>
<p>This filter will match when the message contains the string
"ID-4711". Please note that the comparison is case-sensitive, so it
would not match if "id-4711" would be contained in the message.</p>
<p><code><b>:msg, regex, "fatal .* error"</b></code></p>
<p>This filter uses a POSIX regular expression. It matches when
the
string contains the words "fatal" and "error" with anything in between
(e.g. "fatal net error" and "fatal lib error" but not "fatal error" as
two spaces are required by the regular expression!).</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 "-d" option.</p>
<p>Boolean operations inside property based filters (like
'message contains "ID17" or message contains "ID18"') are currently not
supported (except for "not" 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>
<h3>Expression-Based Filters</h3>
Expression based filters allow
filtering on arbitrary complex expressions, which can include boolean,
arithmetic and string operations. Expression filters will evolve into a
full configuration scripting language. Unfortunately, their syntax will
slightly change during that process. So if you use them now, you need
to be prepared to change your configuration files some time later.
However, we try to implement the scripting facility as soon as possible
(also in respect to stage work needed). So the window of exposure is
probably not too long.<br>
<br>
Expression based filters are indicated by the keyword "if" in column 1
of a new line. They have this format:<br>
<br>
if expr then action-part-of-selector-line<br>
<br>
"If" and "then" are fixed keywords that mus be present. "expr" is a
(potentially quite complex) expression. So the <a href="expression.h">expression documentation</a> for
details. "action-part-of-selector-line" is an action, just as you know
it (e.g. "/var/log/logfile" to write to that file).<br>
<br>
A few quick samples:<br>
<br>
<code>
*.* /var/log/file1 # the traditional way<br>
if $msg contains 'error' /var/log/errlog # the expression-based way<br>
</code>
<br>
Right now, you need to specify numerical values if you would like to
check for facilities and severity. These can be found in <a href="http://www.ietf.org/rfc/rfc3164.txt">RFC 3164</a>.
If you don't like that, you can of course also use the textual property
- just be sure to use the right one. As expression support is enhanced,
this will change. For example, if you would like to filter on message
that have facility local0, start with "DEVNAME" and have either
"error1" or "error0" in their message content, you could use the
following filter:<br>
<br>
<code>
if $syslogfacility-text == 'local0' and $msg
startswith 'DEVNAME' and ($msg contains 'error1' or $msg contains
'error0') then /var/log/somelog<br>
</code>
<br>
Please note that the above <span style="font-weight: bold;">must
all be on one line</span>! And if you would like to store all
messages except those that contain "error1" or "error0", you just need
to add a "not":<br>
<br>
<code>
if $syslogfacility-text == 'local0' and $msg
startswith 'DEVNAME' and <span style="font-weight: bold;">not</span>
($msg contains 'error1' or $msg contains
'error0') then /var/log/somelog<br>
</code>
<br>
If you would like to do case-insensitive comparisons, use
"contains_i" instead of "contains" and "startswith_i" instead of
"startswith".<br>
<br>
Note that regular expressions are currently NOT
supported in expression-based filters. These will be added later when
function support is added to the expression engine (the reason is that
regular expressions will be a separate loadable module, which requires
some more prequisites before it can be implemented).<br>
<h2>ACTIONS</h2>
<p>The action field of a rule describes what to do with the
message. In general, message content is written to a kind of "logfile".
But also other actions might be done, like writing to a database table
or forwarding to another host.<br>
<br>
Templates can be used with all actions. If used, the specified template
is used to generate the message content (instead of the default
template). To specify a template, write a semicolon after the action
value immediately followed by the template name.<br>
<br>
Beware: templates MUST be defined BEFORE they are used. It is OK to
define some templates, then use them in selector lines, define more
templates and use use them in the following selector lines. But it is
NOT permitted to use a template in a selector line that is above its
definition. If you do this, the action will be ignored.</p>
<p><b>You can have multiple actions for a single selector </b> (or
more precisely a single filter of such a selector line). Each action
must be on its own line and the line must start with an ampersand
('&') character and have no filters. An example would be</p>
<p><code><b>*.=crit rger<br>
& root<br>
& /var/log/critmsgs</b></code></p>
<p>These three lines send critical messages to the user rger and
root and also store them in /var/log/critmsgs. <b>Using multiple
actions per selector is</b> convenient and also <b>offers
a performance benefit</b>. As the filter needs to be evaluated
only once, there is less computation required to process the directive
compared to the otherwise-equal config directives below:</p>
<p><code><b>*.=crit rger<br>
*.=crit root<br>
*.=crit /var/log/critmsgs</b></code></p>
<p> </p>
<h3>Regular File</h3>
<p>Typically messages are logged to real files. The file has to
be specified with full pathname, beginning with a slash "/''.<br>
<br>
You may prefix each entry with the minus "-'' sign to omit syncing the
file after every logging. Note that you might lose information if the
system crashes right behind a write attempt. Nevertheless this might
give you back some performance, especially if you run programs that use
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 "-" 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 "DynFile" template defined there. Dynamic
filenames are indicated by specifying a questions mark "?" instead of a
slash, followed by the template name. Thus, the selector line for our
dynamic file name would look as follows:</p>
<blockquote>
<code>*.* ?DynFile</code>
</blockquote>
<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>
<blockquote>
<code>*.* -?DynFile</code></blockquote>
<p>And of course you can use templates to specify the output
format:</p>
<blockquote>
<code>*.* ?DynFile;MyTemplate</code></blockquote>
<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.</p>
<p><b>Creating directories is also supported</b>. For
example you can use the hostname as directory and the program name as
file name:</p>
<blockquote>
<code>$template DynFile,"/var/log/%HOSTNAME%/%programname%.log"</code></blockquote>
<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 "-h" option to enable this.</b></p>
<p>To forward messages to another host, prepend the hostname with
the at sign ("@"). A single at sign means that messages will
be forwarded via UDP protocol (the standard for syslog). If you prepend
two at signs ("@@"), 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 id="table2" border="1" width="100%">
<tbody>
<tr>
<td>
<p align="center"><b>z<number></b></p>
</td>
<td>Enable zlib-compression for the message. The
<number> 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 "no compression". If
given, the "z" 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 seldom seen with typically 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. Messages 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 "o"
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.</p>
</td>
</tr>
<tr>
<td>
<p align="center"><b>o</b></p>
</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
people 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...</p>
</td>
</tr>
</tbody>
</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>*.* @@(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>
<p><b>Note to sysklogd users:</b> sysklogd does <b>not</b>
support RFC 3164 format, which is the default forwarding template in
rsyslog. As such, you will experience duplicate hostnames if rsyslog is
the sender and sysklogd is the receiver. The fix is simple: you need to
use a different template. Use that one:</p>
<p class="MsoPlainText">$template
sysklogd,"<%PRI%>%TIMESTAMP% %syslogtag%%msg%\""<br>
*.* @192.168.0.1;sysklogd</p>
<h3>List of Users</h3>
<p>Usually critical messages are also directed to "root'' on
that machine. You can specify a list of users that shall get the
message by simply writing the login. You may specify more than one user
by separating them with commas (",''). If they're logged in they get
the message. Don't think a mail would be sent, that might be too late.</p>
<h3>Everyone logged on</h3>
<p>Emergency messages often go to all users currently online to
notify them that something strange is happening with the system. To
specify this wall(1)-feature use an asterisk ("*'').</p>
<h3>Call Plugin</h3>
<p>This is a generic way to call an output plugin. The plugin
must support this functionality. Actual parameters depend on the
module, so see the module's doc on what to supply. The general syntax
is as follows:</p>
<p>:modname:params;template</p>
<p>Currently, the ommysql database output module supports this
syntax (in addtion to the ">" syntax it traditionally
supported). For ommysql, the module name is "ommysql" and the params
are the traditional ones. The ;template part is not module specific, it
is generic rsyslog functionality available to all modules.</p>
<p>As an example, the ommysql module may be called as follows:</p>
<p>:ommysql:dbhost,dbname,dbuser,dbpassword;dbtemplate</p>
<p>For details, please see the "Database Table" section of this
documentation.</p>
<p>Note: as of this writing, the ":modname:" part is hardcoded
into the module. So the name to use is not necessarily the name the
module's plugin file is called.</p>
<h3>Database Table</h3>
<p>This allows logging of the message to a database table.
Currently, only MySQL databases are supported. However, other database
drivers will most probably be developed as plugins. By default, a <a href="http://www.monitorware.com/">MonitorWare</a>-compatible
schema is required for this to work. You can create that schema with
the createDB.SQL file that came with the rsyslog package. You can also<br>
use any other schema of your liking - you just need to define a proper
template and assign this template to the action.<br>
<br>
The database writer is called by specifying a greater-then sign
(">") in front of the database connect information. Immediately
after that<br>
sign the database host name must be given, a comma, the database name,
another comma, the database user, a comma and then the user's password.
If a specific template is to be used, a semicolon followed by the
template name can follow the connect information. This is as follows:<br>
<br>
>dbhost,dbname,dbuser,dbpassword;dbtemplate</p>
<p><b>Important: to use the database functionality, the
MySQL output module must be loaded in the config file</b> BEFORE
the first database table action is used. This is done by placing the</p>
<p><code><b>$ModLoad ommysql</b></code></p>
<p>directive some place above the first use of the database write
(we recommend doing at the the beginning of the config file).</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 "discard" 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 retrieve
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>*.* ~</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 "mychannel" to
the action, use "$mychannel". Output channels support template
definitions like all all other actions.</p>
<h3>Shell Execute</h3>
<p>This executes a program in a subshell. The program 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>^program-to-execute;template</p>
<p>The program-to-execute can be any valid executable. It
receives the template string as a single parameter (argv[1]).</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. Lastly, 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 "shell execute" 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 thoroughly, 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 "shell execute" 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
hard-coded default template is used for the action. There can only be
one template name for each given action. The default template is
specific to each action. For a description of what a template is and
what you can do with it, see "TEMPLATES" at the top of this document.</p>
<h2>EXAMPLES</h2>
<p>Below are example for templates and selector lines. I hope
they are self-explanatory. If not, please see
www.monitorware.com/rsyslog/ for advise.</p>
<h3>TEMPLATES</h3>
<p>Please note that the samples are split across multiple lines.
A template MUST NOT actually be split across multiple lines.<br>
<br>
A template that resembles traditional syslogd file output:<br>
$template TraditionalFormat,"%timegenerated% %HOSTNAME%<br>
%syslogtag%%msg:::drop-last-lf%\n"<br>
<br>
A template that tells you a little more about the message:<br>
$template
precise,"%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,<br>
%syslogtag%,%msg%\n"<br>
<br>
A template for RFC 3164 format:<br>
$template RFC3164fmt,"<%PRI%>%TIMESTAMP% %HOSTNAME%
%syslogtag%%msg%"<br>
<br>
A template for the format traditonally used for user messages:<br>
$template usermsg," XXXX%syslogtag%%msg%\n\r"<br>
<br>
And a template with the traditonal wall-message format:<br>
$template wallmsg,"\r\n\7Message from syslogd@%HOSTNAME% at
%timegenerated%<br>
<br>
A template that can be used for the database write (please note the SQL<br>
template option)<br>
$template MySQLInsert,"insert iut, message, receivedat values<br>
('%iut%', '%msg:::UPPERCASE%', '%timegenerated:::date-mysql%')<br>
into systemevents\r\n", SQL<br>
<br>
The following template emulates <a href="http://www.winsyslog.com/en/">WinSyslog</a>
format (it's an <a href="http://www.adiscon.com/en/">Adiscon</a>
format, you do not feel bad if you don't know it ;)). It's interesting
to see how it takes different parts out of the date stamps. What
happens is that the date stamp is split into the actual date and time
and the these two are combined with just a comma in between them.<br>
<br>
$template WinSyslogFmt,"%HOSTNAME%,%timegenerated:1:10:date-rfc3339%,<br>
%timegenerated:12:19:date-rfc3339%,%timegenerated:1:10:date-rfc3339%,<br>
%timegenerated:12:19:date-rfc3339%,%syslogfacility%,%syslogpriority%,<br>
%syslogtag%%msg%\n"</p>
<h3>SELECTOR LINES</h3>
<p># Store critical stuff in critical<br>
#<br>
*.=crit;kern.none /var/adm/critical<br>
<br>
This will store all messages with the priority crit in the file
/var/adm/critical, except for any kernel message.<br>
<br>
<br>
# Kernel messages are first, stored in the kernel<br>
# file, critical messages and higher ones also go<br>
# to another host and to the console. Messages to<br>
# the host finlandia are forwarded in RFC 3164<br>
# format (using the template defined above).<br>
#<br>
kern.* /var/adm/kernel<br>
kern.crit @finlandia;RFC3164fmt<br>
kern.crit /dev/console<br>
kern.info;kern.!err /var/adm/kernel-info<br>
<br>
The first rule direct any message that has the kernel facility to the
file /var/adm/kernel.<br>
<br>
The second statement directs all kernel messages of the priority crit
and higher to the remote host finlandia. This is useful, because if the
host crashes and the disks get irreparable errors you might not be able
to read the stored messages. If they're on a remote host, too, you
still can try to find out the reason for the crash.<br>
<br>
The third rule directs these messages to the actual console, so the
person who works on the machine will get them, too.<br>
<br>
The fourth line tells rsyslogd to save all kernel messages that come
with priorities from info up to warning in the file
/var/adm/kernel-info. Everything from err and higher is excluded.<br>
<br>
<br>
# The tcp wrapper loggs with mail.info, we display<br>
# all the connections on tty12<br>
#<br>
mail.=info /dev/tty12<br>
<br>
This directs all messages that uses mail.info (in source LOG_MAIL |
LOG_INFO) to /dev/tty12, the 12th console. For example the tcpwrapper
tcpd(8) uses this as it's default.<br>
<br>
<br>
# Store all mail concerning stuff in a file<br>
#<br>
mail.*;mail.!=info /var/adm/mail<br>
<br>
This pattern matches all messages that come with the mail facility,
except for the info priority. These will be stored in the file
/var/adm/mail.<br>
<br>
<br>
# Log all mail.info and news.info messages to info<br>
#<br>
mail,news.=info /var/adm/info<br>
<br>
This will extract all messages that come either with mail.info or with
news.info and store them in the file /var/adm/info.<br>
<br>
<br>
# Log info and notice messages to messages file<br>
#<br>
*.=info;*.=notice;\<br>
mail.none /var/log/messages<br>
<br>
This lets rsyslogd log all messages that come with either the info or
the notice facility into the file /var/log/messages, except for all<br>
messages that use the mail facility.<br>
<br>
<br>
# Log info messages to messages file<br>
#<br>
*.=info;\<br>
mail,news.none /var/log/messages<br>
<br>
This statement causes rsyslogd to log all messages that come with the
info priority to the file /var/log/messages. But any message coming
either with the mail or the news facility will not be stored.<br>
<br>
<br>
# Emergency messages will be displayed using wall<br>
#<br>
*.=emerg *<br>
<br>
This rule tells rsyslogd to write all emergency messages to all
currently logged in users. This is the wall action.<br>
<br>
<br>
# Messages of the priority alert will be directed<br>
# to the operator<br>
#<br>
*.alert root,rgerhards<br>
<br>
This rule directs all messages with a priority of alert or higher to
the terminals of the operator, i.e. of the users "root'' and
"rgerhards'' if they're logged in.<br>
<br>
<br>
*.* @finlandia<br>
<br>
This rule would redirect all messages to a remote host called
finlandia. This is useful especially in a cluster of machines where all
syslog messages will be stored on only one machine.<br>
<br>
In the format shown above, UDP is used for transmitting the message.
The destination port is set to the default auf 514. Rsyslog is also
capable of using much more secure and reliable TCP sessions for message
forwarding. Also, the destination port can be specified. To select TCP,
simply add one additional @ in front of the host name (that is, @host
is UPD, @@host is TCP). For example:<br>
<br>
<br>
*.* @@finlandia<br>
<br>
To specify the destination port on the remote machine, use a colon
followed by the port number after the machine name. The following
forwards to port 1514 on finlandia:<br>
<br>
<br>
*.* @@finlandia:1514<br>
<br>
This syntax works both with TCP and UDP based syslog. However, you will
probably primarily need it for TCP, as there is no well-accepted port
for this transport (it is non-standard). For UDP, you can usually stick
with the default auf 514, but might want to modify it for security rea-<br>
sons. If you would like to do that, it's quite easy:<br>
<br>
<br>
*.* @finlandia:1514<br>
<br>
<br>
<br>
*.* >dbhost,dbname,dbuser,dbpassword;dbtemplate<br>
<br>
This rule writes all message to the database "dbname" hosted on
"dbhost". The login is done with user "dbuser" and password
"dbpassword". The actual table that is updated is specified within the
template (which contains the insert statement). The template is called
"dbtemplate" in this case.</p>
<p>:msg,contains,"error" @errorServer</p>
<p>This rule forwards all messages that contain the word "error"
in the msg part to the server "errorServer". 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>
</p>
</body></html>
|
