summaryrefslogtreecommitdiffstats
path: root/doc/v3compatibility.html
blob: b17aca82ab92b1b2c695b1dc93c75a06283970cc (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
122
123
124
125
126
127
128
129
<!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>
(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 # 30 minutes</b></p>
<h2>-r command line option</h2>
<p>Is&nbsp; no longer available in native mode. However, it is
understood in compatibility mode (if no -c option is given). 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>"$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.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 "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.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 "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>
<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>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&lt;vers&gt; where vers is the
rsyslog version that it shall be compatible to. Use -c0 to be
command-line compatible to sysklogd.</p><p>Note that at of this writing, there may still be some command line options not fully supported.</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 "Call Encapsulation", 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...? ;) It is scheduled to be solved by the
"rsyslog loader", for which some stage work has already been done.</p>
<p>&nbsp;</p>
</body></html>