1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
<html><head><title>Global Directives - rsyslog.conf</title></head>
4
<p>This is a part of the rsyslog.conf documentation.</p>
5
<a href="rsyslog_conf.html">back</a>
6
<h2>Global Directives</h2>
7
<p>All global directives need to be specified on a line by their
8
own and must start with a dollar-sign. Here is a list in alphabetical
9
order. Follow links for a description.</p>
10
<p>Please note that not all directives here are actually global. Some affect
11
only the next action. This documentation will be changed soon.
12
<p>Not all directives have an in-depth description right now.
13
Default values for them are in bold. A more in-depth description will
14
appear as implementation progresses.
16
<p><b>Be sure to read information about <a href="queues.html">queues in rsyslog</a></b> -
17
many parameter settings modify queue parameters. If in doubt, use the
18
default, it is usually well-chosen and applicable in most cases.</p>
20
<li><a href="rsconf1_actionexeconlywhenpreviousissuspended.html">$ActionExecOnlyWhenPreviousIsSuspended</a></li>
21
<li>$ActionExecOnlyOnceEveryInterval <seconds> -
22
execute action only if the last execute is at last
23
<seconds> seconds in the past (more info in <a href="ommail.html">ommail</a>,
24
but may be used with any action)</li>
25
<li><i><b>$ActionExecOnlyEveryNthTime</b> <number></i> - If configured, the next action will
26
only be executed every n-th time. For example, if configured to 3, the first two messages
27
that go into the action will be dropped, the 3rd will actually cause the action to execute,
28
the 4th and 5th will be dropped, the 6th executed under the action, ... and so on. Note:
29
this setting is automatically re-set when the actual action is defined.</li>
30
<li><i><b>$ActionExecOnlyEveryNthTimeTimeout</b> <number-of-seconds></i> - has a meaning only if
31
$ActionExecOnlyEveryNthTime is also configured for the same action. If so, the timeout
32
setting specifies after which period the counting of "previous actions" expires and
33
a new action count is begun. Specify 0 (the default) to disable timeouts.
35
<i>Why is this option needed?</i> Consider this case: a message comes in at, eg., 10am. That's
36
count 1. Then, nothing happens for the next 10 hours. At 8pm, the next
37
one occurs. That's count 2. Another 5 hours later, the next message
38
occurs, bringing the total count to 3. Thus, this message now triggers
41
The question is if this is desired behavior? Or should the rule only be
42
triggered if the messages occur within an e.g. 20 minute window? If the
43
later is the case, you need a
45
$ActionExecOnlyEveryNthTimeTimeout 1200
47
This directive will timeout previous messages seen if they are older
48
than 20 minutes. In the example above, the count would now be always 1
49
and consequently no rule would ever be triggered.
51
<li>$ActionFileDefaultTemplate [templateName] - sets a new default template for file actions</li>
52
<li>$ActionFileEnableSync [on/<span style="font-weight: bold;">off</span>] - enables file
53
syncing capability of omfile</li>
54
<li>$ActionForwardDefaultTemplate [templateName] - sets a new
55
default template for UDP and plain TCP forwarding action</li>
56
<li>$ActionGSSForwardDefaultTemplate [templateName] - sets a
57
new default template for GSS-API forwarding action</li>
58
<li>$ActionQueueCheckpointInterval <number></li>
59
<li>$ActionQueueDequeueSlowdown <number> [number
60
is timeout in <i> micro</i>seconds (1000000us is 1sec!),
61
default 0 (no delay). Simple rate-limiting!]</li>
62
<li>$ActionQueueDiscardMark <number> [default
64
<li>$ActionQueueDiscardSeverity <number>
65
[*numerical* severity! default 4 (warning)]</li>
66
<li>$ActionQueueFileName <name></li>
67
<li>$ActionQueueHighWaterMark <number> [default
69
<li>$ActionQueueImmediateShutdown [on/<b>off</b>]</li>
70
<li>$ActionQueueSize <number></li>
71
<li>$ActionQueueLowWaterMark <number> [default
73
<li>$ActionQueueMaxFileSize <size_nbr>, default 1m</li>
74
<li>$ActionQueueTimeoutActionCompletion <number>
75
[number is timeout in ms (1000ms is 1sec!), default 1000, 0 means
77
<li>$ActionQueueTimeoutEnqueue <number> [number
78
is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]</li>
79
<li>$ActionQueueTimeoutShutdown <number> [number
80
is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]</li>
81
<li>$ActionQueueWorkerTimeoutThreadShutdown
82
<number> [number is timeout in ms (1000ms is 1sec!),
83
default 60000 (1 minute)]</li>
84
<li>$ActionQueueType [FixedArray/LinkedList/<b>Direct</b>/Disk]</li>
85
<li>$ActionQueueSaveOnShutdown [on/<b>off</b>]
87
<li>$ActionQueueWorkerThreads <number>, num worker threads, default 1, recommended 1</li>
88
<li>$ActionQueueWorkerThreadMinumumMessages <number>, default 100</li>
89
<li><a href="rsconf1_actionresumeinterval.html">$ActionResumeInterval</a></li>
90
<li>$ActionResumeRetryCount <number> [default 0, -1 means eternal]</li>
91
<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.
92
<li>$ActionSendStreamDriver <driver basename> just like $DefaultNetstreamDriver, but for the specific action
93
</li><li>$ActionSendStreamDriverMode <mode>, default 0, mode to use with the stream driver
94
(driver-specific)</li><li>$ActionSendStreamDriverAuthMode <mode>, authentication mode to use with the stream driver
95
(driver-specific)</li><li>$ActionSendStreamDriverPermittedPeer <ID>, accepted fingerprint (SHA1) or name of remote peer
96
(driver-specific) -<span style="font-weight: bold;"> directive may go away</span>!</li>
97
<li><a href="rsconf1_allowedsender.html">$AllowedSender</a></li>
98
<li><a href="rsconf1_controlcharacterescapeprefix.html">$ControlCharacterEscapePrefix</a></li>
99
<li><a href="rsconf1_debugprintcfsyslinehandlerlist.html">$DebugPrintCFSyslineHandlerList</a></li>
101
<li><a href="rsconf1_debugprintmodulelist.html">$DebugPrintModuleList</a></li>
102
<li><a href="rsconf1_debugprinttemplatelist.html">$DebugPrintTemplateList</a></li>
103
<li>$DefaultNetstreamDriver <drivername>, the default <a href="netstream.html">network stream driver</a> to use. Defaults to ptcp.$DefaultNetstreamDriverCAFile </path/to/cafile.pem></li>
104
<li>$DefaultNetstreamDriverCertFile </path/to/certfile.pem></li>
105
<li>$DefaultNetstreamDriverKeyFile </path/to/keyfile.pem></li>
106
<li><b>$CreateDirs</b> [<b>on</b>/off] - create directories on an as-needed basis</li>
107
<li><a href="rsconf1_dircreatemode.html">$DirCreateMode</a></li>
108
<li><a href="rsconf1_dirgroup.html">$DirGroup</a></li>
109
<li><a href="rsconf1_dirowner.html">$DirOwner</a></li>
110
<li><a href="rsconf1_dropmsgswithmaliciousdnsptrrecords.html">$DropMsgsWithMaliciousDnsPTRRecords</a></li>
111
<li><a href="rsconf1_droptrailinglfonreception.html">$DropTrailingLFOnReception</a></li>
112
<li><a href="rsconf1_dynafilecachesize.html">$DynaFileCacheSize</a></li>
113
<li><a href="rsconf1_escapecontrolcharactersonreceive.html">$EscapeControlCharactersOnReceive</a></li>
114
<li>$ErrorMessagesToStderr [<b>on</b>|off] - direct rsyslogd error message to stderr (in addition to other targets)</li>
115
<li><a href="rsconf1_failonchownfailure.html">$FailOnChownFailure</a></li>
116
<li><a href="rsconf1_filecreatemode.html">$FileCreateMode</a></li>
117
<li><a href="rsconf1_filegroup.html">$FileGroup</a></li>
118
<li><a href="rsconf1_fileowner.html">$FileOwner</a></li>
119
<li><a href="rsconf1_gssforwardservicename.html">$GssForwardServiceName</a></li>
120
<li><a href="rsconf1_gsslistenservicename.html">$GssListenServiceName</a></li>
121
<li><a href="rsconf1_gssmode.html">$GssMode</a></li>
122
<li>$HUPisRestart [<b>on</b>/off] - if set to on, a HUP is a full daemon restart. This means any queued messages are discarded (depending
123
on queue configuration, of course) all modules are unloaded and reloaded. This mode keeps compatible with sysklogd, but is
124
not recommended for use with rsyslog. To do a full restart, simply stop and start the daemon. The default is "on" for
125
compatibility reasons. If it is set to "off", a HUP will only close open files. This is a much quicker action and usually
126
the only one that is needed e.g. for log rotation. <b>It is recommended to set the setting to "off".</b></li>
127
<li><a href="rsconf1_includeconfig.html">$IncludeConfig</a></li><li>MainMsgQueueCheckpointInterval <number></li>
128
<li>$MainMsgQueueDequeueSlowdown <number> [number
129
is timeout in <i> micro</i>seconds (1000000us is 1sec!),
130
default 0 (no delay). Simple rate-limiting!]</li>
131
<li>$MainMsgQueueDiscardMark <number> [default 9750]</li>
132
<li>$MainMsgQueueDiscardSeverity <severity>
133
[either a textual or numerical severity! default 4 (warning)]</li>
134
<li>$MainMsgQueueFileName <name></li>
135
<li>$MainMsgQueueHighWaterMark <number> [default
137
<li>$MainMsgQueueImmediateShutdown [on/<b>off</b>]</li>
138
<li><a href="rsconf1_mainmsgqueuesize.html">$MainMsgQueueSize</a></li>
139
<li>$MainMsgQueueLowWaterMark <number> [default
141
<li>$MainMsgQueueMaxFileSize <size_nbr>, default
143
<li>$MainMsgQueueTimeoutActionCompletion
144
<number> [number is timeout in ms (1000ms is 1sec!),
146
1000, 0 means immediate!]</li>
147
<li>$MainMsgQueueTimeoutEnqueue <number> [number
148
is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]</li>
149
<li>$MainMsgQueueTimeoutShutdown <number> [number
150
is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]</li>
151
<li>$MainMsgQueueWorkerTimeoutThreadShutdown
152
<number> [number is timeout in ms (1000ms is 1sec!),
153
default 60000 (1 minute)]</li>
154
<li>$MainMsgQueueType [<b>FixedArray</b>/LinkedList/Direct/Disk]</li>
155
<li>$MainMsgQueueSaveOnShutdown [on/<b>off</b>]
157
<li>$MainMsgQueueWorkerThreads <number>, num
158
worker threads, default 1, recommended 1</li>
159
<li>$MainMsgQueueWorkerThreadMinumumMessages <number>, default 100</li>
160
<li><a href="rsconf1_markmessageperiod.html">$MarkMessagePeriod</a> (immark)</li>
161
<li><b><i>$MaxMessageSize</i></b> <size_nbr>, default 2k - allows to specify maximum supported message size
162
(both for sending and receiving). The default
163
should be sufficient for almost all cases. Do not set this below 1k, as it would cause
164
interoperability problems with other syslog implementations.<br>
165
Change the setting to e.g. 32768 if you would like to
166
support large message sizes for IHE (32k is the current maximum
167
needed for IHE). I was initially tempted to set the default to 32k,
168
but there is a some memory footprint with the current
169
implementation in rsyslog.
170
<br>If you intend to receive Windows Event Log data (e.g. via
171
<a href="http://www.eventreporter.com/">EventReporter</a>), you might want to
172
increase this number to an even higher value, as event
173
log messages can be very lengthy ("$MaxMessageSize 64k" is not a bad idea).
174
Note: testing showed that 4k seems to be
175
the typical maximum for <b>UDP</b> based syslog. This is an IP stack
176
restriction. Not always ... but very often. If you go beyond
177
that value, be sure to test that rsyslogd actually does what
178
you think it should do ;) It is highly suggested to use a TCP based transport
179
instead of UDP (plain TCP syslog, RELP). This resolves the UDP stack size restrictions.
180
<br>Note that 2k, the current default, is the smallest size that must be
181
supported in order to be compliant to the upcoming new syslog RFC series.
183
<li><a href="rsconf1_moddir.html">$ModDir</a></li>
184
<li><a href="rsconf1_modload.html">$ModLoad</a></li>
185
<li><b>$RepeatedMsgContainsOriginalMsg</b> [on/<b>off</b>] - "last message repeated n times" messages, if generated,
186
have a different format that contains the message that is being repeated.
187
Note that only the first "n" characters are included, with n to be at least 80 characters, most
188
probably more (this may change from version to version, thus no specific limit is given). The bottom
189
line is that n is large enough to get a good idea which message was repeated but it is not necessarily
190
large enough for the whole message. (Introduced with 4.1.5). Once set, it affects all following actions.</li>
191
<li><a href="rsconf1_repeatedmsgreduction.html">$RepeatedMsgReduction</a></li>
192
<li><a href="rsconf1_resetconfigvariables.html">$ResetConfigVariables</a></li>
193
<li><b>$OptimizeForUniprocessor</b> [on/<b>off</b>] - turns on optimizatons which lead to better
194
performance on uniprocessors. If you run on multicore-machiens, turning this off lessens CPU load. The
195
default may change as uniprocessor systems become less common.</li>
196
<li>$PreserveFQDN [on/<b>off</b>) - if set to off (legacy default to remain compatible
197
to sysklogd), the domain part from a name that is within the same domain as the receiving
198
system is stripped. If set to on, full names are always used.</li>
199
<li>$WorkDirectory <name> (directory for spool and other work files)</li>
200
<li>$UDPServerAddress <IP> (imudp) -- local IP
201
address (or name) the UDP listens should bind to</li>
202
<li>$UDPServerRun <port> (imudp) -- former
203
-r<port> option, default 514, start UDP server on this
204
port, "*" means all addresses</li>
205
<li>$UDPServerTimeRequery <nbr-of-times> (imudp) -- this is a performance
206
optimization. Getting the system time is very costly. With this setting, imudp can
207
be instructed to obtain the precise time only once every n-times. This logic is
208
only activated if messages come in at a very fast rate, so doing less frequent
209
time calls should usually be acceptable. The default value is two, because we have
210
seen that even without optimization the kernel often returns twice the identical time.
211
You can set this value as high as you like, but do so at your own risk. The higher
212
the value, the less precise the timestamp.
213
<li><a href="droppriv.html">$PrivDropToGroup</a></li>
214
<li><a href="droppriv.html">$PrivDropToGroupID</a></li>
215
<li><a href="droppriv.html">$PrivDropToUser</a></li>
216
<li><a href="droppriv.html">$PrivDropToUserID</a></li>
218
<li><a href="rsconf1_umask.html">$UMASK</a></li>
220
<p><b>Where <size_nbr> is specified above,</b>
221
modifiers can be used after the number part. For example, 1k means
222
1024. Supported are k(ilo), m(ega), g(iga), t(era), p(eta) and e(xa).
223
Lower case letters refer to the traditional binary defintion (e.g. 1m
224
equals 1,048,576) whereas upper case letters refer to their new
225
1000-based definition (e.g 1M equals 1,000,000).</p>
226
<p>Numbers may include '.' and ',' for readability. So you can
227
for example specify either "1000" or "1,000" with the same result.
228
Please note that rsyslogd simply ignores the punctuation. Form it's
229
point of view, "1,,0.0.,.,0" also has the value 1000. </p>
231
<p>[<a href="manual.html">manual index</a>]
232
[<a href="rsyslog_conf.html">rsyslog.conf</a>]
233
[<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
234
<p><font size="2">This documentation is part of the
235
<a href="http://www.rsyslog.com/">rsyslog</a> project.<br>
236
Copyright © 2008, 2009 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
237
<a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL
238
version 2 or higher.</font></p>
added
removed
doc/rsyslog_conf_global.html
