diff options
| author | Rainer Gerhards <rgerhards@adiscon.com> | 2008-03-27 17:55:00 +0000 |
|---|---|---|
| committer | Rainer Gerhards <rgerhards@adiscon.com> | 2008-03-27 17:55:00 +0000 |
| commit | 82eb4472b6669df0483611801776f219903e1f42 (patch) | |
| tree | 77be1a025a2d9309a8056c9a2071cf572cc3e14a /doc | |
| parent | 90516819d5b8bef3dfa3902155eb32efc2685e04 (diff) | |
| download | rsyslog-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.html | 6 | ||||
| -rw-r--r-- | doc/v3compatibility.html | 137 |
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 # provides --MARK-- +<p><b>$ModLoad immark # provides --MARK-- message capability<br> -$ModLoad imudp.so # provides UDP syslog reception<br> -$ModLoad imtcp.so # 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 # provides UDP syslog reception<br> +$ModLoad imtcp # provides TCP syslog reception<br> +</b><b>$ModLoad imgssapi # 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 # 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 , +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.</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 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 <port></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. </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<vers> 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> </p> </body></html>
\ No newline at end of file |