diff options
Diffstat (limited to 'source/compatibility/v3compatibility.rst')
| -rw-r--r-- | source/compatibility/v3compatibility.rst | 260 |
1 files changed, 260 insertions, 0 deletions
diff --git a/source/compatibility/v3compatibility.rst b/source/compatibility/v3compatibility.rst new file mode 100644 index 0000000..502ca64 --- /dev/null +++ b/source/compatibility/v3compatibility.rst @@ -0,0 +1,260 @@ +Compatibility Notes for rsyslog v3 +================================== + +*Written by* `Rainer Gerhards <http://www.gerhards.net/rainer>`_ +*(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 statements 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 / Compatibility Mode +------------------------------ + +The -c option is new and tells 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. + +Please note that rsyslogd issues warning messages if the -c3 command +line option is not given. This is to alert you that your are running in +compatibility mode. Compatibility mode interferes with your rsyslog.conf +commands and may cause some undesired side-effects. It is meant to be +used with a plain old rsyslog.conf - if you use new features, things +become messy. So the best advise is to work through this document, +convert your options and config file and then use rsyslog in native +mode. In order to aid you in this process, rsyslog logs every +compatibility-mode config file directive it has generated. So you can +simply copy them from your logfile and paste them to the config. + +-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 dedicated `forum thread on "last message repeated n +times" <http://www.rsyslog.com/PNphpBB2-viewtopic-p-1130.phtml>`_. 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 compatibility mode. To replace +it, use the following config directives (compatibility mode +auto-generates them): + +:: + + $ModLoad immark + $MarkMessagePeriod 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 + $UDPServerAddress 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 + $UDPServerAddress 192.0.2.1 # this MUST be before the $UDPServerRun directive! + $UDPServerRun 514 + $UDPServerAddress \* # all local interfaces + $UDPServerRun 1514 + +These config file settings run two listeners: one at 192.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 consistency, 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 + +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 +world. Instead, the syncing is a high performance 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. + +Output File Format +------------------ + +Rsyslog supports high precision RFC 3339 timestamps and puts these into +local log files by default. This is a departure from previous syslogd +behaviour. We decided to sacrifice some backward-compatibility in an +effort to provide a better logging solution. Rsyslog has been supporting +the high-precision timestamps for over three years as of this writing, +but nobody used them because they were not default (one may also assume +that most people didn't even know about them). Now, we are writing the +great high-precision time stamps, which greatly aid in getting the right +sequence of logging events. If you do not like that, you can easily turn +them off by placing + +:: + + $ActionFileDefaultTemplate RSYSLOG_TraditionalFileFormat + +right at the start of your rsyslog.conf. This will use the previous +format. Please note that the name is case-sensitive and must be +specified exactly as shown above. Please also note that you can of +course use any other format of your liking. To do so, simply specify the +template to use or set a new default template via the +$ActionFileDefaultTemplate directive. Keep in mind, though, that +templates must be defined before they are used. + +Keep in mind that when receiving messages from remote hosts, the +timestamp is just as precise as the remote host provided it. In most +cases, this means you will only a receive a standard timestamp with +second precision. If rsyslog is running at the remote end, you can +configure it to provide high-precision timestamps (see below). + +Forwarding Format +----------------- + +When forwarding messages to remote syslog servers, rsyslogd by default +uses the plain old syslog format with second-level resolution inside the +timestamps. We could have made it emit high precision timestamps. +However, that would have broken almost all receivers, including earlier +versions of rsyslog. To avoid this hassle, high-precision timestamps +need to be explicitly enabled. To make this as painless as possible, +rsyslog comes with a canned template that contains everything necessary. + To enable high-precision timestamps, just use: + +:: + + $ActionForwardDefaultTemplate RSYSLOG_ForwardFormat # for plain TCP and UDP + $ActionGSSForwardDefaultTemplate RSYSLOG_ForwardFormat # for GSS-API + +And, of course, you can always set different forwarding formats by just +specifying the right template. + +If you are running in a system with only rsyslog 3.12.5 and above in the +receiver roles, it is suggested to add one (or both) of the above +statements to the top of your rsyslog.conf (but after the $ModLoad's!) - +that will enable you to use the best in timestamp support available. +Please note that when you use this format with other receivers, they +will probably become pretty confused and not detect the timestamp at +all. In earlier rsyslog versions, for example, that leads to duplication +of timestamp and hostname fields and disables the detection of the +original hostname in a relayed/NATed environment. So use the new format +with care. + +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). |