Configuration Directives

This is a part of the rsyslog.conf documentation.

Configuration Directives

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.

Here is a list in alphabetical order. Follow links for a description.

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.

Be sure to read information about queues in rsyslog - many parameter settings modify queue parameters. If in doubt, use the default, it is usually well-chosen and applicable in most cases.

$ActionExecOnlyWhenPreviousIsSuspended
$ActionName <a_single_word> - used primarily for documentation, e.g. when generating a configuration graph. Available sice 4.3.1.
$ActionExecOnlyOnceEveryInterval <seconds> - execute action only if the last execute is at last <seconds> seconds in the past (more info in ommail, but may be used with any action)
$ActionExecOnlyEveryNthTime <number> - 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.
$ActionExecOnlyEveryNthTimeTimeout <number-of-seconds> - 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.
Why is this option needed? 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.
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
$ActionExecOnlyEveryNthTimeTimeout 1200
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.
$ActionFileDefaultTemplate [templateName] - sets a new default template for file actions
$ActionFileEnableSync [on/off] - enables file syncing capability of omfile
$ActionForwardDefaultTemplate [templateName] - sets a new default template for UDP and plain TCP forwarding action
$ActionGSSForwardDefaultTemplate [templateName] - sets a new default template for GSS-API forwarding action
$ActionQueueCheckpointInterval <number>
$ActionQueueDequeueBatchSize <number> [default 16]
$ActionQueueDequeueSlowdown <number> [number is timeout in microseconds (1000000us is 1sec!), default 0 (no delay). Simple rate-limiting!]
$ActionQueueDiscardMark <number> [default 9750]
$ActionQueueDiscardSeverity <number> [*numerical* severity! default 4 (warning)]
$ActionQueueFileName <name>
$ActionQueueHighWaterMark <number> [default 8000]
$ActionQueueImmediateShutdown [on/off]
$ActionQueueSize <number>
$ActionQueueLowWaterMark <number> [default 2000]
$ActionQueueMaxFileSize <size_nbr>, default 1m
$ActionQueueTimeoutActionCompletion <number> [number is timeout in ms (1000ms is 1sec!), default 1000, 0 means immediate!]
$ActionQueueTimeoutEnqueue <number> [number is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]
$ActionQueueTimeoutShutdown <number> [number is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]
$ActionQueueWorkerTimeoutThreadShutdown <number> [number is timeout in ms (1000ms is 1sec!), default 60000 (1 minute)]
$ActionQueueType [FixedArray/LinkedList/Direct/Disk]
$ActionQueueSaveOnShutdown [on/off]
$ActionQueueWorkerThreads <number>, num worker threads, default 1, recommended 1
$ActionQueueWorkerThreadMinumumMessages <number>, default 100
$ActionResumeInterval
$ActionResumeRetryCount <number> [default 0, -1 means eternal]
$ActionSendResendLastMsgOnReconn <[on/off]> 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.
$ActionSendStreamDriver <driver basename> just like $DefaultNetstreamDriver, but for the specific action
$ActionSendStreamDriverMode <mode>, default 0, mode to use with the stream driver (driver-specific)
$ActionSendStreamDriverAuthMode <mode>, authentication mode to use with the stream driver (driver-specific)
$ActionSendStreamDriverPermittedPeer <ID>, accepted fingerprint (SHA1) or name of remote peer (driver-specific) - directive may go away!
$ActionSendUDPRebindInterval nbr- [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.
$AllowedSender
$ControlCharacterEscapePrefix
$DebugPrintCFSyslineHandlerList
$DebugPrintModuleList
$DebugPrintTemplateList
$DefaultNetstreamDriver <drivername>, the default network stream driver to use. Defaults to ptcp.$DefaultNetstreamDriverCAFile </path/to/cafile.pem>
$DefaultNetstreamDriverCertFile </path/to/certfile.pem>
$DefaultNetstreamDriverKeyFile </path/to/keyfile.pem>
$DefaultRuleset name - changes the default ruleset for unbound inputs to the provided name (the default default ruleset is named "RSYSLOG_DefaultRuleset").
$CreateDirs [on/off] - create directories on an as-needed basis
$DirCreateMode
$DirGroup
$DirOwner
$DropMsgsWithMaliciousDnsPTRRecords
$DropTrailingLFOnReception
$DynaFileCacheSize
$EscapeControlCharactersOnReceive
$ErrorMessagesToStderr [on|off] - direct rsyslogd error message to stderr (in addition to other targets)
$FailOnChownFailure
$FileCreateMode
$FileGroup
$FileOwner
$GenerateConfigGraph
$GssForwardServiceName
$GssListenServiceName
$GssMode
$HUPisRestart [on/off] - 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 is "on" for compatibility reasons. 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. It is recommended to set the setting to "off".
$IncludeConfig
MainMsgQueueCheckpointInterval <number>
$MainMsgQueueDequeueBatchSize <number> [default 32]
$MainMsgQueueDequeueSlowdown <number> [number is timeout in microseconds (1000000us is 1sec!), default 0 (no delay). Simple rate-limiting!]
$MainMsgQueueDiscardMark <number> [default 9750]
$MainMsgQueueDiscardSeverity <severity> [either a textual or numerical severity! default 4 (warning)]
$MainMsgQueueFileName <name>
$MainMsgQueueHighWaterMark <number> [default 8000]
$MainMsgQueueImmediateShutdown [on/off]
$MainMsgQueueSize
$MainMsgQueueLowWaterMark <number> [default 2000]
$MainMsgQueueMaxFileSize <size_nbr>, default 1m
$MainMsgQueueTimeoutActionCompletion <number> [number is timeout in ms (1000ms is 1sec!), default 1000, 0 means immediate!]
$MainMsgQueueTimeoutEnqueue <number> [number is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]
$MainMsgQueueTimeoutShutdown <number> [number is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]
$MainMsgQueueWorkerTimeoutThreadShutdown <number> [number is timeout in ms (1000ms is 1sec!), default 60000 (1 minute)]
$MainMsgQueueType [FixedArray/LinkedList/Direct/Disk]
$MainMsgQueueSaveOnShutdown [on/off]
$MainMsgQueueWorkerThreads <number>, num worker threads, default 1, recommended 1
$MainMsgQueueWorkerThreadMinumumMessages <number>, default 100
$MarkMessagePeriod (immark)
$MaxMessageSize <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.
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.
If you intend to receive Windows Event Log data (e.g. via EventReporter), 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 UDP 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.
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.
$MaxOpenFiles
$ModDir
$ModLoad
$OMFileZipLevel 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.
$OMFileIOBufferSize <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)
$OMFileFlushOnTXEnd <[on/off]>, default on. Omfile has the capability to writes 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 each 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 -off- is primarily an aid to preserve the traditional syslogd behaviour.
$RepeatedMsgContainsOriginalMsg [on/off] - "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.
$RepeatedMsgReduction
$ResetConfigVariables
$Ruleset name - starts a new ruleset or switches back to one already defined. All following actions belong to that new rule set. the name 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.
$OptimizeForUniprocessor [on/off] - 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]
$PreserveFQDN [on/off) - 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.
$WorkDirectory <name> (directory for spool and other work files)
$UDPServerAddress <IP> (imudp) -- local IP address (or name) the UDP listens should bind to
$UDPServerRun <port> (imudp) -- former -r<port> option, default 514, start UDP server on this port, "*" means all addresses
$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.
$PrivDropToGroup
$PrivDropToGroupID
$PrivDropToUser
$PrivDropToUserID
$UMASK

Where <size_nbr> is specified above, 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).

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.

[manual index] [rsyslog.conf] [rsyslog site]