Use this documentation with care! It describes
the heavily outdated version 5, which was actively
developed around 2010 and is considered dead by the
rsyslog team for many years now.
This documentation reflects the latest update of the previously existing (now removed) v5-stable branch. It describes the 5.10.2 version, which was never released. As such, it contains some content that does not apply to any released version.
To obtain the doc that properly matches your installed v5 version, obtain the doc set from your distro. Each version of rsyslog contained the version that exactly matches it.
As general advise, it is strongly suggested to upgrade to the current version supported by the rsyslog project. The current version can always be found on the right-hand side info box on the rsyslog web site.
Note that there is no rsyslog community support available for this heavily outdated version. If you need to stick with it, please ask your distribution for support.
Global Configuration Statements¶
Global configuration statements, as their name implies, usually affect some global features. However, some also affect main queues, which are “global” to a ruleset.
True Global Directives¶
$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.
Important: In order for this directive to work correctly, it must be placed right at the top of
rsyslog.conf(before any input is defined).
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.
$LocalHostName [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+.
$LogRSyslogStatusMessages [on/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. [available since 4.7.0 and 5.3.0]
$DefaultRuleset [name] - changes the default ruleset for unbound inputs to the provided name (the default default ruleset is named “RSYSLOG_DefaultRuleset”). It is advised to also read our paper on using multiple rule sets in rsyslog.
$DefaultNetstreamDriver <drivername>, the default network stream driver to use. Defaults to ptcp.
$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.
$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. Do not use trailing slashes)
$Sleep <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!
$LocalHostIPIF <interface name> - (available since 5.9.6) - if provided, the IP of the specified interface (e.g. “eth0”) shall be used as fromhost-ip for locall-originating messages. If this directive is not given OR the interface cannot be found (or has no IP address), the default of “127.0.0.1” is used. Note that this directive can be given only once. Trying to reset will result in an error message and the new value will be ignored. Please note that modules must have support for obtaining the local IP address set via this directive. While this is the case for rsyslog-provided modules, it may not always be the case for contributed plugins. Important: This directive shall be placed right at the top of rsyslog.conf. Otherwise, if error messages are triggered before this directive is processed, rsyslog will fix the local host IP to “127.0.0.1”, what than can not be reset.
$ErrorMessagesToStderr [on|off] - direct rsyslogd error message to stderr (in addition to other targets)
$SpaceLFOnReceive [on/off] - instructs rsyslogd to replace LF with spaces during message reception (sysklogd compatibility aid). This is applied at the beginning of the parser stage and cannot be overridden (neither at the input nor parser level). Consequently, it affects all inputs and parsers.
main queue specific Directives¶
Note that these directives modify ruleset main message queues. This includes the default ruleset’s main message queue, the one that is always present. To do this, specify directives outside of a ruleset definition.
To understand queue parameters, read queues in rsyslog.
- $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]
- $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