From 227c44dbe0f3ce8ab465829c2d6114d5e6b38470 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Thu, 21 Feb 2008 09:41:56 +0000 Subject: cleanup for 3.11.4 --- doc/v3compatibility.html | 196 ++++++++++++++++++++++++++--------------------- 1 file changed, 108 insertions(+), 88 deletions(-) (limited to 'doc/v3compatibility.html') diff --git a/doc/v3compatibility.html b/doc/v3compatibility.html index 4a391f97..221d8302 100644 --- a/doc/v3compatibility.html +++ b/doc/v3compatibility.html @@ -1,119 +1,139 @@ - +Compatibility notes for rsyslog v3 -Writing syslog Data to MySQL + +

Compatibility notes for rsyslog v3

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

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 ;)

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

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

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.so # provides --MARK-- message capability
+

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.so # 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. via -logger command)
-$ModLoad imklog.so # provides kernel logging support (previously done by rklogd)
+$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. +via logger command)
+$ModLoad imklog.so # 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. Once we implement compatibiltiy mode, these -options will return, but only if running in non-v3-native mode.

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

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
$MarkMessageInterval 1800 # 30 minutes

-r command line option

Is also no longer available. 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:

Is also no longer available. 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!
+$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:

"$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!
+$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.

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 serves, 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".

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

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 via -rsyslog.conf. That set of configuration directives is to be expanded. So far, we -support:

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

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).

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.

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

needs to be implemented. So far, only -c3 is supported. Everything else does -not change anything but just provides a warning message. In short: there is no -backwards compatibility yet.

needs to be implemented. So far, only -c3 is supported. +Everything else does not change anything but just provides a warning +message. In short: there is no backwards compatibility yet.

Thread Termination

Thread termination in mode 1 needs to be looked at. I begin to think that it -is OK if we simply cancel the thread, because we already have a different -cleanup function. Otherwise, there is a potential for a race condition after we -unblocked the TermOK mutex but before select() is entered. If the signal then -occurs, we may have a problem. However, I would like to create the other input -modules first so that I have more working experience with termination -requirements. Again, I think this will lead to changes in thread termination.

So far, this issue is resolved, but there is still some code present that -needs to go away (right now disabled). I keep it in because I will make the -final decision based on experience gained during creation of input modules.

Thread termination in mode 1 needs to be looked at. I begin to +think that it is OK if we simply cancel the thread, because we already +have a different cleanup function. Otherwise, there is a potential for +a race condition after we unblocked the TermOK mutex but before +select() is entered. If the signal then occurs, we may have a problem. +However, I would like to create the other input modules first so that I +have more working experience with termination requirements. Again, I +think this will lead to changes in thread termination.

So far, this issue is resolved, but there is still some code +present that needs to go away (right now disabled). I keep it in +because I will make the final decision based on experience gained +during creation of input modules.

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.

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

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
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...? ;)

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...? ;)

\ No newline at end of file -- cgit