diff options
Diffstat (limited to 'doc/v3compatibility.html')
| -rw-r--r-- | doc/v3compatibility.html | 196 |
1 files changed, 0 insertions, 196 deletions
diff --git a/doc/v3compatibility.html b/doc/v3compatibility.html deleted file mode 100644 index 1c15350..0000000 --- a/doc/v3compatibility.html +++ /dev/null @@ -1,196 +0,0 @@ -<!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> -$MarkMessagePeriod 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> -$UDPServerAddress 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> -$UDPServerAddress 192.0.2.1 # this MUST be before the $UDPServerRun -directive!<br> -$UDPServerRun 514<br> -$UDPServerAddress * # 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> |