summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorRainer Gerhards <rgerhards@adiscon.com>2008-03-27 17:55:00 +0000
committerRainer Gerhards <rgerhards@adiscon.com>2008-03-27 17:55:00 +0000
commit82eb4472b6669df0483611801776f219903e1f42 (patch)
tree77be1a025a2d9309a8056c9a2071cf572cc3e14a /doc
parent90516819d5b8bef3dfa3902155eb32efc2685e04 (diff)
downloadrsyslog-82eb4472b6669df0483611801776f219903e1f42.tar.gz
rsyslog-82eb4472b6669df0483611801776f219903e1f42.tar.xz
rsyslog-82eb4472b6669df0483611801776f219903e1f42.zip
updated v3 compatibility doc to cover new compatibility mode
Diffstat (limited to 'doc')
-rw-r--r--doc/status.html6
-rw-r--r--doc/v3compatibility.html137
2 files changed, 71 insertions, 72 deletions
diff --git a/doc/status.html b/doc/status.html
index 22786c84..6cdcd54d 100644
--- a/doc/status.html
+++ b/doc/status.html
@@ -2,12 +2,12 @@
<html><head><title>rsyslog status page</title></head>
<body>
<h2>rsyslog status page</h2>
-<p>This page reflects the status as of 2008-03-25.</p>
+<p>This page reflects the status as of 2008-03-28.</p>
<h2>Current Releases</h2>
<p><b>development:</b> 3.12.4 -
-<a href="http://www.rsyslog.com/Article195.phtml">change
+<a href="http://www.rsyslog.com/Article199.phtml">change
log</a> -
-<a href="http://www.rsyslog.com/Downloads-index-req-getit-lid-89.phtml">download</a></p>
+<a href="http://www.rsyslog.com/Downloads-index-req-getit-lid-91.phtml">download</a></p>
<p><b><font color="#ff0000"><a href="v3compatibility.html">If you used version 2, be sure to read the rsyslog v3
compatibility document!</a></font></b><br>
Documentation for 3.x is currently partly sparse. If you need
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 @@
<!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>
+<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>
+(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.</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>
+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.
@@ -25,28 +33,51 @@ 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--
+<p><b>$ModLoad immark&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.
+$ModLoad imudp&nbsp; # provides UDP syslog reception<br>
+$ModLoad imtcp&nbsp; # provides TCP syslog reception<br>
+</b><b>$ModLoad imgssapi&nbsp; # provides GSSAPI syslog
+reception<br>
+</b><b>$ModLoad imuxsock # provides support for local
+system logging (e.g.
via logger command)<br>
-$ModLoad imklog.so # provides kernel logging support (previously done
+$ModLoad imklog # provides kernel logging support (previously done
by rklogd)</b></p>
-<h2>command line options</h2>
+<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>
+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</h2>
+<p>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&nbsp;,
+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>
+<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>
$MarkMessageInterval 1800 # 30 minutes</b></p>
-<h2>-r command line option</h2>
-<p>Is&nbsp; no longer available in native mode. However, it is
+<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
&lt;port&gt;</b> config file directives. You can now also
set the local address the server should listen to via <b>$UDPServerAddress
@@ -74,7 +105,7 @@ interfaces.</p>
<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
+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>
@@ -82,12 +113,13 @@ the "Run" directive, e.g. "<i>$UDPServerRun syslog</i>".</p>
<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
+<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. So far, we support:</p>
-<p>$klogSymbolsTwice [on/off]<br>
-$DebugPrintKernelSymbols [on/off] # spits *a lot* of messages at startup</p>
-<h2>Output File Syncing</h2>Rsyslogd tries to keep as compatible to
+expanded.&nbsp;</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
@@ -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.<h2>Queue Modes for the Main Message Queue</h2>
+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>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> \ No newline at end of file