Compatibility notes for rsyslog v3

Written by Rainer Gerhards (2008-03-28)

Rsyslog aims to be a drop-in replacement for sysklogd. However, version 3 has some considerable enhancements, which lead to some backward compatibility issues both in regard to sysklogd and rsyslog v1 and v2. Most of these issues are avoided by default by not specifying the -c option on the rsyslog command line. That will enable backwards-compatibility mode. However, please note that things may be suboptimal in backward compatibility mode, so the advise is to work through this document, update your rsyslog.conf, remove the no longer supported startup options and then add -c3 as the first option to the rsyslog command line. That will enable native mode.

Please note that rsyslogd helps you during that process by logging appropriate messages about compatibility mode and backwards-compatibility statemtents automatically generated. You may want your syslogd log for those. They immediately follow rsyslogd's startup message.

Inputs

With v2 and below, inputs were automatically started together with rsyslog. In v3, inputs are optional! They come in the form of plug-in modules. At least one input module must be loaded to make rsyslog do any useful work. The config file directives doc briefly lists which config statements are available by which modules.

It is suggested that input modules be loaded in the top part of the config file. Here is an example, also highlighting the most important modules:

$ModLoad immark # provides --MARK-- message capability
$ModLoad imudp # provides UDP syslog reception
$ModLoad imtcp # provides TCP syslog reception
$ModLoad imgssapi # provides GSSAPI syslog reception
$ModLoad imuxsock # provides support for local system logging (e.g. via logger command)
$ModLoad imklog # provides kernel logging support (previously done by rklogd)

Command Line Options

A number of command line options have been removed. New config file directives have been added for them. The -h and -e option have been removed even in compatibility mode. They are ignored but an informative message is logged. Please note that -h was never supported in v2, but was silently ignored. It disappeared some time ago in the final v1 builds. It can be replaced by applying proper filtering inside syslog.conf.

-c option

The -c option is new and tell rsyslogd about the desired backward compatibility mode. It must always be the first option on the command line, as it influences processing of the other options. To use the rsyslog v3 native interface, specify -c3. To use compatibility mode , either do not use -c at all or use -c<vers> where vers is the rsyslog version that it shall be compatible to. Use -c0 to be command-line compatible to sysklogd.

-e Option

This option is no longer supported, as the "last message repeated n times" feature is now turned off by default. We changed this default because this feature is causing a lot of trouble and we need to make it either go away or change the way it works. For more information, please see our dedicted forum thread on "last message repeated n times". This thread also contains information on how to configure rsyslogd so that it continues to support this feature (as long as it is not totally removed).

-m Option

The -m command line option is emulated in compatibiltiy mode. To replace it, use the following config directives (compatibility mode auto-generates them):

$ModLoad immark
$MarkMessageInterval 1800 # 30 minutes

-r Option

Is no longer available in native mode. However, it is understood in compatibility mode (if no -c option is given). Use the $UDPSeverRun <port> config file directives. You can now also set the local address the server should listen to via $UDPServerAddress <ip> config directive.

The following example configures an UDP syslog server at the local address 192.0.2.1 on port 514:

$ModLoad imudp.so
$UDPSeverAddress 192.0.2.1 # this MUST be before the $UDPServerRun directive!
$UDPServerRun 514

"$UDPServerAddress *" means listen on all local interfaces. This is the default if no directive is specified.

Please note that now multiple listeners are supported. For example, you can do the following:

$ModLoad imudp.so
$UDPSeverAddress 192.0.2.1 # this MUST be before the $UDPServerRun directive!
$UDPServerRun 514
$UDPSeverAddress * # all local interfaces
$UDPServerRun 1514

These config file settings run two listeners: one at192.0.2.1:514 and one on port 1514, which listens on all local interfaces.

Default port for UDP (and TCP) Servers

Please note that with pre-v3 rsyslogd, a service database lookup was made when a UDP server was started and no port was configured. Only if that failed, the IANA default of 514 was used. For TCP servers, this lookup was never done and 514 always used if no specific port was configured. For consitency, both TCP and UDP now use port 514 as default. If a lookup is desired, you need to specify it in the "Run" directive, e.g. "$UDPServerRun syslog".

klogd

klogd has (finally) been replaced by a loadable input module. To enable klogd functionality, do

$ModLoad imklog.so

Note that this can not be handled by the compatibility layer, as klogd was a separate binary.A limited set of klogd command line settings is now supported via rsyslog.conf. That set of configuration directives is to be expanded.

Output File Syncing

Rsyslogd tries to keep as compatible to stock syslogd as possible. As such, it retained stock syslogd's default of syncing every file write if not specified otherwise (by placing a dash in front of the output file name). While this was a useful feature in past days where hardware was much less reliable and UPS seldom, this no longer is useful in today's worl. Instead, the syncing is a high performace hit. With it, rsyslogd writes files around 50 *times* slower than without it. It also affects overall system performance due to the high IO activity. In rsyslog v3, syncing has been turned off by default. This is done via a specific configuration directive "$ActionFileEnableSync on/off" which is off by default. So even if rsyslogd finds sync selector lines, it ignores them by default. In order to enable file syncing, the administrator must specify "$ActionFileEnableSync on" at the top of rsyslog.conf. This ensures that syncing only happens in some installations where the administrator actually wanted that (performance-intense) feature. In the fast majority of cases (if not all), this dramatically increases rsyslogd performance without any negative effects.

Queue Modes for the Main Message Queue

Either "FixedArray" or "LinkedList" is recommended. "Direct" is available, but should not be used except for a very good reason ("Direct" disables queueing and will potentially lead to message loss on the input side).