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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>Configuration Directives - rsyslog.conf</title></head>
<body>
<p>This is a part of the rsyslog.conf documentation.</p>
<a href="rsyslog_conf.html">back</a>
<h2>Configuration Directives</h2>
<p>All configuration directives need to be specified on a line by their
own and must start with a dollar-sign. Note that those starting with
the word "Action" modify the next action and should be specified
in front of it.
<p>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.
</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>$ActionName <a_single_word> - used primarily for documentation, e.g. when
generating a configuration graph. Available sice 4.3.1.
<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><i><b>$ActionExecOnlyEveryNthTime</b> <number></i> - If configured, the next action will
only be executed every n-th time. For example, if configured to 3, the first two messages
that go into the action will be dropped, the 3rd will actually cause the action to execute,
the 4th and 5th will be dropped, the 6th executed under the action, ... and so on. Note:
this setting is automatically re-set when the actual action is defined.</li>
<li><i><b>$ActionExecOnlyEveryNthTimeTimeout</b> <number-of-seconds></i> - has a meaning only if
$ActionExecOnlyEveryNthTime is also configured for the same action. If so, the timeout
setting specifies after which period the counting of "previous actions" expires and
a new action count is begun. Specify 0 (the default) to disable timeouts.
<br>
<i>Why is this option needed?</i> Consider this case: a message comes in at, eg., 10am. That's
count 1. Then, nothing happens for the next 10 hours. At 8pm, the next
one occurs. That's count 2. Another 5 hours later, the next message
occurs, bringing the total count to 3. Thus, this message now triggers
the rule.
<br>
The question is if this is desired behavior? Or should the rule only be
triggered if the messages occur within an e.g. 20 minute window? If the
later is the case, you need a
<br>
$ActionExecOnlyEveryNthTimeTimeout 1200
<br>
This directive will timeout previous messages seen if they are older
than 20 minutes. In the example above, the count would now be always 1
and consequently no rule would ever be triggered.
<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. Note that this directive requires TLS
netstream drivers. For all others, it will be ignored.
(driver-specific)</li>
<li>$ActionSendStreamDriverPermittedPeer <ID>, accepted fingerprint (SHA1) or name of remote peer. Note that this directive requires TLS
netstream drivers. For all others, it will be ignored.
(driver-specific) -<span style="font-weight: bold;"> directive may go away</span>!</li>
<li><b>$ActionSendTCPRebindInterval</b> nbr</a>- [available since 4.5.1] - instructs the TCP send
action to close and re-open the connection to the remote host every nbr of messages sent.
Zero, the default, means that no such processing is done. This directive is useful for
use with load-balancers. Note that there is some performance overhead associated with it,
so it is advisable to not too often "rebind" the connection (what
"too often" actually means depends on your configuration, a rule of thumb is
that it should be not be much more often than once per second).</li>
<li><b>$ActionSendUDPRebindInterval</b> nbr</a>- [available since 4.3.2] - instructs the UDP send
action to rebind the send socket every nbr of messages sent. Zero, the default, means
that no rebind is done. This directive is useful for use with load-balancers.</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><b>$DefaultRuleset</b> <i>name</i> - changes the default ruleset for unbound inputs to
the provided <i>name</i> (the default default ruleset is named
"RSYSLOG_DefaultRuleset"). It is advised to also read
our paper on <a href="multi_ruleset.html">using multiple rule sets in rsyslog</a>.</li>
<li><b>$CreateDirs</b> [<b>on</b>/off] - create directories on an as-needed basis</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><b>$EscapeControlCharactersOnReceive</b> [<b>on</b>|off] - escape USASCII HT character</li>
<li>$ErrorMessagesToStderr [<b>on</b>|off] - direct rsyslogd error message to stderr (in addition to other targets)</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_generateconfiggraph.html">$GenerateConfigGraph</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>$HUPisRestart [on/<b>off</b>] - if set to on, a HUP is a full daemon restart. This means any queued messages are discarded (depending
on queue configuration, of course) all modules are unloaded and reloaded. This mode keeps compatible with sysklogd, but is
not recommended for use with rsyslog. To do a full restart, simply stop and start the daemon. The default (since 4.5.1) is "off".
If it is set to "off", a HUP will only close open files. This is a much quicker action and usually
the only one that is needed e.g. for log rotation. <b>Restart-type HUPs (value "on") are depricated</b>
and will go away in rsyslog v5. So it is a good idea to change anything that needs it, now.
Usually that should not be a big issue, as the restart-type HUP can easily be replaced by
something along the lines of "/etc/init.d/rsyslog restart".
</li>
<li><a href="rsconf1_includeconfig.html">$IncludeConfig</a></li><li>MainMsgQueueCheckpointInterval <number></li>
<li><b>$LocalHostName</b> [name] - this directive permits to overwrite the system
hostname with the one specified in the directive. If the directive is given
multiple times, all but the last one will be ignored. Please note that startup
error messages may be issued with the real hostname. This is by design and not
a bug (but one may argue if the design should be changed ;)). Available since
4.7.4+, 5.7.3+, 6.1.3+.
<li><b>$LogRSyslogStatusMessages</b> [<b>on</b>/off] - If set to on (the default),
rsyslog emits message on startup and shutdown as well as when it is HUPed.
This information might be needed by some log analyzers. If set to off, no such
status messages are logged, what may be useful for other scenarios.
<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><b><i>$MaxMessageSize</i></b> <size_nbr>, default 2k - allows to specify maximum supported message size
(both for sending and receiving). The default
should be sufficient for almost all cases. Do not set this below 1k, as it would cause
interoperability problems with other syslog implementations.<br>
Change the setting to e.g. 32768 if you would like to
support large message sizes for IHE (32k is the current maximum
needed for IHE). I was initially tempted to set the default to 32k,
but there is a some memory footprint with the current
implementation in rsyslog.
<br>If you intend to receive Windows Event Log data (e.g. via
<a href="http://www.eventreporter.com/">EventReporter</a>), you might want to
increase this number to an even higher value, as event
log messages can be very lengthy ("$MaxMessageSize 64k" is not a bad idea).
Note: testing showed that 4k seems to be
the typical maximum for <b>UDP</b> based syslog. This is an IP stack
restriction. Not always ... but very often. If you go beyond
that value, be sure to test that rsyslogd actually does what
you think it should do ;) It is highly suggested to use a TCP based transport
instead of UDP (plain TCP syslog, RELP). This resolves the UDP stack size restrictions.
<br>Note that 2k, the current default, is the smallest size that must be
supported in order to be compliant to the upcoming new syslog RFC series.
</li>
<li><a href="rsconf1_maxopenfiles.html">$MaxOpenFiles</a></li>
<li><a href="rsconf1_moddir.html">$ModDir</a></li>
<li><a href="rsconf1_modload.html">$ModLoad</a></li>
<li><b>$OMFileAsyncWriting</b> [on/<b>off</b>], if turned on, the files will be written
in asynchronous mode via a separate thread. In that case, double buffers will be used so
that one buffer can be filled while the other buffer is being written. Note that in order
to enable $OMFileFlushInterval, $OMFileAsyncWriting must be set to "on". Otherwise, the flush
interval will be ignored. Also note that when $OMFileFlushOnTXEnd is "on" but
$OMFileAsyncWriting is off, output will only be written when the buffer is full. This may take
several hours, or even require a rsyslog shutdown. However, a buffer flush can be forced
in that case by sending rsyslogd a HUP signal.
<li><b>$OMFileZipLevel</b> 0..9 [default 0] - if greater 0, turns on gzip compression
of the output file. The higher the number, the better the compression, but also the
more CPU is required for zipping.</li>
<li><b>$OMFileIOBufferSize</b> <size_nbr>, default 4k, size of the buffer used to writing output data. The larger the buffer, the potentially better performance is. The default of 4k is quite conservative, it is useful to go up to 64k, and 128K if you used gzip compression (then, even higher sizes may make sense)</li>
<li><b>$OMFileFlushOnTXEnd</b> <[<b>on</b>/off]>, default on. Omfile has the
capability to
write output using a buffered writer. Disk writes are only done when the buffer is
full. So if an error happens during that write, data is potentially lost. In cases where
this is unacceptable, set $OMFileFlushOnTXEnd to on. Then, data is written at the end
of each transaction (for pre-v5 this means after <b>each</b> log message) and the usual
error recovery thus can handle write errors without data loss. Note that this option
severely reduces the effect of zip compression and should be switched to off
for that use case. Note that the default -on- is primarily an aid to preserve
the traditional syslogd behaviour.</li>
<li><a href="rsconf1_omfileforcechown.html">$omfileForceChown</a> - force ownership change for all files</li>
<li><b>$RepeatedMsgContainsOriginalMsg</b> [on/<b>off</b>] - "last message repeated n times" messages, if generated,
have a different format that contains the message that is being repeated.
Note that only the first "n" characters are included, with n to be at least 80 characters, most
probably more (this may change from version to version, thus no specific limit is given). The bottom
line is that n is large enough to get a good idea which message was repeated but it is not necessarily
large enough for the whole message. (Introduced with 4.1.5). Once set, it affects all following actions.</li>
<li><a href="rsconf1_repeatedmsgreduction.html">$RepeatedMsgReduction</a></li>
<li><a href="rsconf1_resetconfigvariables.html">$ResetConfigVariables</a></li>
<li><b>$Ruleset</b> <i>name</i> - starts a new ruleset or switches back to one already defined.
All following actions belong to that new rule set.
the <i>name</i> does not yet exist, it is created. To swith back to rsyslog's
default ruleset, specify "RSYSLOG_DefaultRuleset") as the name.
All following actions belong to that new rule set. It is advised to also read
our paper on <a href="multi_ruleset.html">using multiple rule sets in rsyslog</a>.</li>
<li><b>$OptimizeForUniprocessor</b> [on/<b>off</b>] - turns on optimizatons which lead to better
performance on uniprocessors. If you run on multicore-machiens, turning this off lessens CPU load. The
default may change as uniprocessor systems become less common. [available since 4.1.0]</li>
<li>$PreserveFQDN [on/<b>off</b>) - if set to off (legacy default to remain compatible
to sysklogd), the domain part from a name that is within the same domain as the receiving
system is stripped. If set to on, full names are always used.</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>$UDPServerTimeRequery <nbr-of-times> (imudp) -- this is a performance
optimization. Getting the system time is very costly. With this setting, imudp can
be instructed to obtain the precise time only once every n-times. This logic is
only activated if messages come in at a very fast rate, so doing less frequent
time calls should usually be acceptable. The default value is two, because we have
seen that even without optimization the kernel often returns twice the identical time.
You can set this value as high as you like, but do so at your own risk. The higher
the value, the less precise the timestamp.
<li><a href="droppriv.html">$PrivDropToGroup</a></li>
<li><a href="droppriv.html">$PrivDropToGroupID</a></li>
<li><a href="droppriv.html">$PrivDropToUser</a></li>
<li><a href="droppriv.html">$PrivDropToUserID</a></li>
<li><b>$Sleep</b> <seconds> - puts the rsyslog main thread to sleep for the specified
number of seconds immediately when the directive is encountered. You should have a
good reason for using this directive!</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>
<p>[<a href="manual.html">manual index</a>]
[<a href="rsyslog_conf.html">rsyslog.conf</a>]
[<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
<p><font size="2">This documentation is part of the
<a href="http://www.rsyslog.com/">rsyslog</a> project.<br>
Copyright © 2008-2010 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
<a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL
version 3 or higher.</font></p>
</body>
</html>
|
