diff options
Diffstat (limited to 'doc/v3compatibility.html')
| -rw-r--r-- | doc/v3compatibility.html | 196 |
1 files changed, 196 insertions, 0 deletions
diff --git a/doc/v3compatibility.html b/doc/v3compatibility.html new file mode 100644 index 00000000..51619947 --- /dev/null +++ b/doc/v3compatibility.html @@ -0,0 +1,196 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head><title>Compatibility notes for rsyslog v3</title> + +<meta name="KEYWORDS" content="syslog, mysql, syslog to mysql, howto"></head> +<body> +<h1>Compatibility Notes for rsyslog v3</h1> +<p><small><i>Written by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> +(2008-03-28)</i></small></p> +<p>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.</p> +<p>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.</p> +<h2>Inputs</h2> +<p>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. +<font color="#ff0000"><b>At least one input module +must be loaded to make rsyslog do any useful work.</b></font> +The config file directives doc briefly lists which config statements +are available by which modules.</p> +<p>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:</p> +<p><b>$ModLoad immark # provides --MARK-- +message capability<br> +$ModLoad imudp # provides UDP syslog reception<br> +$ModLoad imtcp # provides TCP syslog reception<br> +</b><b>$ModLoad imgssapi # provides GSSAPI syslog +reception<br> +</b><b>$ModLoad imuxsock # provides support for local +system logging (e.g. +via logger command)<br> +$ModLoad imklog # provides kernel logging support (previously done +by rklogd)</b></p> +<h2>Command Line Options</h2> +<p>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.</p> +<h2>-c option / Compatibility Mode</h2> +<p>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.</p><p><span style="font-weight: bold;">Please note that rsyslogd issues warning messages if the -c3 command line option is not given.</span> +This is to alert you that your are running in compatibility mode. +Compatibility mode interfers with you 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.</p> +<h2>-e Option</h2> +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 <a href="http://www.rsyslog.com/PNphpBB2-viewtopic-p-1130.phtml">forum +thread on "last message repeated n times"</a>. 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). +<h2>-m Option</h2> +<p>The -m command line option is emulated in compatibiltiy mode. +To replace it, use the following config directives (compatibility mode +auto-generates them):</p> +<p><b>$ModLoad immark<br> +$MarkMessageInterval 1800 # 30 minutes</b></p> +<h2>-r Option</h2> +<p>Is no longer available in native mode. However, it +is +understood in compatibility mode (if no -c option is given). Use the <b>$UDPSeverRun +<port></b> config file directives. You can now also +set the local address the server should listen to via <b>$UDPServerAddress +<ip></b> config directive.</p> +<p>The following example configures an UDP syslog server at the +local address 192.0.2.1 on port 514:</p> +<p><b>$ModLoad imudp<br> +$UDPSeverAddress 192.0.2.1 # this MUST be before the $UDPServerRun +directive!<br> +$UDPServerRun 514</b></p> +<p>"$UDPServerAddress *" means listen on all local interfaces. +This is the default if no directive is specified.</p> +<p>Please note that now multiple listeners are supported. For +example, you can do the following:</p> +<p><b>$ModLoad imudp<br> +$UDPSeverAddress 192.0.2.1 # this MUST be before the $UDPServerRun +directive!<br> +$UDPServerRun 514<br> +$UDPSeverAddress * # all local interfaces<br> +$UDPServerRun 1514</b></p> +<p>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.</p> +<h2>Default port for UDP (and TCP) Servers</h2> +<p>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. "<i>$UDPServerRun syslog</i>".</p> +<h2>klogd</h2> +<p>klogd has (finally) been replaced by a loadable input module. +To enable klogd functionality, do</p> +<p><b>$ModLoad imklog</b></p> +<p>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. </p> +<h2>Output File Syncing</h2> +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. +<h2>Output File Format</h2> +<p>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 sacrify 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 +</p><p style="font-weight: bold;"><code>$ActionFileDefaultTemplate RSYSLOG_TraditionalFileFormat</code> +</p><p>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 specificed 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.</p><p>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).</p><h2>Forwarding Format</h2><p>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 explicitely 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:</p><p style="font-weight: bold;"><code>$ActionForwardDefaultTemplate RSYSLOG_ForwardFormat # for plain TCP and UDP</code></p><p style="font-weight: bold;"><code>$ActionGSSForwardDefaultTemplate RSYSLOG_ForwardFormat # for GSS-API</code></p><p>And, of course, you can always set different forwarding formats by just specifying the right template.</p><p>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 availble. +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 orignal hostname in a relayed/NATed environment. So use the new +format with care. </p><h2>Queue Modes for the Main Message Queue</h2> +<p>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).</p> +</body></html> |