summaryrefslogtreecommitdiffstats
path: root/doc/v3compatibility.html
blob: c3e0d601b82d1843a548cc42327e665921c034c6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
<html><head>
<title>Writing syslog Data to MySQL</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> (2007-12-17)</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.</P>
<P>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 ;)</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.so&nbsp; # provides --MARK-- message capability<br>
$ModLoad imudp.so&nbsp; # provides UDP syslog reception<br>
$ModLoad imtcp.so&nbsp; # provides TCP syslog reception and GSS-API (if compiled 
to support it)<br>
$ModLoad imuxsock.so # provides support for local system logging (e.g. via 
logger command)<br>
$ModLoad imklog.so # 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. Once we implement compatibiltiy mode, these 
options will return, but only if running in non-v3-native mode.</p>
<h2>-m command line option</h2>
<P>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</P>
<P><b>$ModLoad immark.so&nbsp; # wherever this is<br>
$MarkMessageInterval 1800 # 20 minutes</b></P>
<h2>-r command line option</h2>
<p>Is also no longer available. Use the <b>$UDPSeverRun &lt;port&gt;</b> config file 
directives. You can now also set the local address the server should listen to 
via <b>$UDPServerAddress &lt;ip&gt;</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.so<br>
$UDPSeverAddress 192.0.2.1 # this MUST be before the $UDPServerRun directive!<br>
$UDPServerRun 514</b></p>
<p>&quot;$UDPServerAddress *&quot; 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.so<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 at192.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 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 &quot;Run&quot; directive, e.g. &quot;<i>$UDPServerRun syslog</i>&quot;.</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.so</b></P>
<P>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:</P>
<P>$klogSymbolsTwice [on/off]<br>
$DebugPrintKernelSymbols [on/off] # spits *a lot* of messages at startup</P>
<h2>Queue Modes for the Main Message Queue</h2>
<p>Either &quot;FixedArray&quot; or &quot;LinkedList&quot; is recommended. &quot;Direct&quot; is available, 
but should not be used except for a very good reason (&quot;Direct&quot; disables queueing 
and will potentially lead to message loss on the input side).</p>
<h1>TODO List</h1>
<P>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.</P>
<h2>-c option</h2>
<P>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.</P>
<h2>Thread Termination</h2>
<p>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.</p>
<p>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.</p>
<h2>Call Encapsulation</h2>
<p>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.</p>
<h2>No real Modules yet</h2>
<p>As already said in &quot;Call Encapsulation&quot;, the modules look like such, but are 
not really able to work stand alone. The worst in this regard are</p>
<ul>
	<li>imudp/omfwd/syslogd.c</li>
	<li>imtcp</li>
</ul>
<p>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...? ;)</p>
<p>&nbsp;</p>
</body>
</html>