From 82eb4472b6669df0483611801776f219903e1f42 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Thu, 27 Mar 2008 17:55:00 +0000 Subject: updated v3 compatibility doc to cover new compatibility mode --- doc/v3compatibility.html | 137 +++++++++++++++++++++++------------------------ 1 file changed, 68 insertions(+), 69 deletions(-) (limited to 'doc/v3compatibility.html') diff --git a/doc/v3compatibility.html b/doc/v3compatibility.html index c2a51139..562fbbc5 100644 --- a/doc/v3compatibility.html +++ b/doc/v3compatibility.html @@ -1,20 +1,28 @@ Compatibility notes for rsyslog v3 - + +

Compatibility notes for rsyslog v3

Written by Rainer Gerhards -(2007-12-17)

+(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.

Rsyslog v3 is currently under initial development. -Compatibility issues may be resolved, so be sure to check back often. -Also, comments and suggestions are appreciated. Feedback right in time -can now have a big impact on the route we take ;)

inputs

+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. @@ -25,28 +33,51 @@ 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.so # provides --MARK-- +

$ModLoad immark # provides --MARK-- message capability
-$ModLoad imudp.so # provides UDP syslog reception
-$ModLoad imtcp.so # provides TCP syslog reception and GSS-API -(if compiled to support it)
-$ModLoad imuxsock.so # provides support for local system logging (e.g. +$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.so # provides kernel logging support (previously done +$ModLoad imklog # provides kernel logging support (previously done by rklogd)

-
command line options
+
Command Line Options

A number of command line options have been removed. New config -file directives have been added for them. Once we implement -compatibiltiy mode, these options will return, but only if running in -non-v3-native mode.
-
-m command line option
-
The -m command line option is ignored for the time being. -There is no default mark period. If you need a 20 minute mark period -you need to
-
$ModLoad immark.so # wherever this is
+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 command line option
-
Is no longer available in native mode. However, it is +
-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 @@ -74,7 +105,7 @@ interfaces.

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 serves, this lookup was never done and 514 always used if no +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".
@@ -82,12 +113,13 @@ the "Run" directive, e.g. "$UDPServerRun syslog".

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

$ModLoad imklog.so
-
A limited set of klogd command line settings is now supported +
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. So far, we support:
-
$klogSymbolsTwice [on/off]
-$DebugPrintKernelSymbols [on/off] # spits *a lot* of messages at startup
-
Output File Syncing
Rsyslogd tries to keep as compatible to +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 @@ -101,46 +133,13 @@ default. This is done via a specific configuration directive 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 those 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
+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).
-
TODO List
-
I have decided to move the todo list for v3 also into this -document. After all, it is kind of a compatibility issue ;) But, more -seriously, I think this is a good place to make sure nothing is -forgotten. Remember that as of now, rsyslog v3 is in its early stage of -development and so there definitely are some nits that will give you -grief. This section here tells you what it is.
-
-c option
-
is at least partly implemented. To use the rsyslog v3 native -interface, specify -c3. To use legacy mode (command line options!), -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.
Note that at of this writing, there may still be some command line options not fully supported.
Call Encapsulation
-
In an ideal world, the modules should call back only to some -well-defined and specifically exported interface functions. Right now, -we do not have an ideal world and the input modules make some calls -back into the core. This needs to be re-thought but is accepted for the -time being.
-
No real Modules yet
-
As already said in "Call Encapsulation", the modules look like -such, but are not really able to work stand alone. The worst in this -regard are
-
-
imudp/omfwd/syslogd.c
-
imtcp
-
-
But the others are not necessarily better. I have moved the -code to the modules, because now at least the majority of code is where -it belongs to. But there are still a large number of global variables, -cross-function calls and the like. This needs to be solved when we try -to claim a real modular design. That's not an easy task, but, hey, -aren't we up for that...? ;) It is scheduled to be solved by the -"rsyslog loader", for which some stage work has already been done.
-

\ No newline at end of file -- cgit