Merge branch 'master' into beta

Conflicts: ChangeLog configure.ac doc/manual.html
author: Rainer Gerhards <rgerhards@adiscon.com> 2008-11-11 12:54:44 +0100
committer: Rainer Gerhards <rgerhards@adiscon.com> 2008-11-11 12:54:44 +0100
commit: 05bd696ebb7766f33b3ae176b841bcecb0bfedfc (patch)
tree: 99437759863ee4b25174f49aa69807c207176a76 /doc
parent: 9048c16d90177a0dfa4131266ae73f029a5923c8 (diff)
parent: ba201a941435bc5fec2c333155e1a8e16c4a9c05 (diff)
download: rsyslog-05bd696ebb7766f33b3ae176b841bcecb0bfedfc.tar.gz
rsyslog-05bd696ebb7766f33b3ae176b841bcecb0bfedfc.tar.xz
rsyslog-05bd696ebb7766f33b3ae176b841bcecb0bfedfc.zip
12 files changed, 318 insertions, 71 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 4f4aae19..22d368e0 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -26,7 +26,7 @@ html_files = \
 	rsyslog_tls.html \
 	rsyslog_reliable_forwarding.html \
 	rsyslog_stunnel.html \
-	syslog-protocol.html \
+	syslog_protocol.html \
 	version_naming.html \
 	contributors.html \
 	dev_queue.html \
diff --git a/doc/features.html b/doc/features.html
index 2b3b31d9..d221eb77 100644
--- a/doc/features.html
+++ b/doc/features.html
@@ -74,7 +74,7 @@ easy multi-host support</li>
 <li> massively multi-threaded with dynamic work thread pools
 that start up and shut themselves down on an as-needed basis (great for
 high log volume on multicore machines)</li>
-<li>very experimental and volatile support for <a href="syslog-protocol.html">syslog-protocol</a>
+<li>very experimental and volatile support for <a href="syslog_protocol.html">syslog-protocol</a>
 compliant messages (it is volatile because standardization is currently
 underway and this is a proof-of-concept implementation to aid this
 effort)</li>
@@ -94,6 +94,7 @@ loadable plug-in</li>
 via custom plugins</li>
 <li> an easy-to-write to plugin interface</li>
 <li> ability to send SNMP trap messages</li>
+<li> ability to filter out messages based on sequence of arrival</li>
 <li>support for arbitrary complex boolean, string and
 arithmetic expressions in message filters</li>
 </ul>
diff --git a/doc/free_support.html b/doc/free_support.html
new file mode 100644
index 00000000..182a82cd
--- /dev/null
+++ b/doc/free_support.html
@@ -0,0 +1,56 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head>
+<meta http-equiv="Content-Language" content="en">
+<title>Free Support for Rsyslog</title>
+
+</head>
+<body>
+<h1>Free Services for Rsyslog</h1>
+<p><i>A personal word from Rainer, the lead developer of rsyslog:</i>
+<p><b>The rsyslog community provides ample free support resources. Please see our
+<a href="troubleshoot.html">troubleshooting guide</a> to get started.</b></p>
+<p>Every now and then I receive private mail with support questions. I appreciate
+any feedback, but I must limit my resources so that I can help driver a great logging
+system forward.
+<p>To do so, I have decided not to reply to unsolicited support emails, at least not
+with a solution (but rather a link to this page ;)). I hope this does not offend you. The
+reason is quite simple: If I do personal support, you gain some advantage without
+contributing something back. Think about it: if you ask your question on the public
+forum or mailing list, other with the same problem can you and, most importantly, even
+years later find your post (and the answer) and get the problem solved. So by
+solving your issue in public, you help create a great community ressource and also
+help your fellow users finding solutions quicker. In the long term, this
+also contributes to improved code because the more questions users can find
+solutions to themselves, the fewer I need to look at.
+<p>But it comes even better: the rsyslog community is much broader than Rainer ;) - there
+are helpful other members hanging around at the public places. They often answer
+questions, so that I do not need to look at them (btw, once again a big "thank you", folks!).
+And, more important, those folks have different background than me. So they often
+either know better how to solve your problem (e.g. because it is distro-specific)
+or they know how to better phrase it (after all, I like abstract terms and concepts ;)).
+So you do yourself a favor if you use the public places.
+<p>An excellent place to go to is the
+<a href="http://kb.monitorware.com/rsyslog-f40.html">rsyslog forum</a> inside the
+knowledge base (which in itself is a great place to visit!). For those used to
+mailing lists, the
+<a href="http://lists.adiscon.net/mailman/listinfo/rsyslog">rsyslog mailing list</a>
+also offers excellent advise.
+<p><b>Don't like to post your question in a public place?</b> Well, then you should
+consider purchasing <a href="professional_support.html">rsyslog professional support</a>.
+The fees are very low and help fund the project. If you use rsyslog seriously inside
+a corporate environment, there is no excuse for not getting one of the support
+packages ;)
+<p>Of course, things are different when I ask you to mail me privately. I'll usually do
+that when I think it makes sense, for example when we exchange debug logs.
+<p>I hope you now understand the free support options and the reasoning for them.
+I hope I haven't offended you with my words - this is not my intension. I just needed to
+make clear why there are some limits on my responsiveness. Happy logging!
+<p>[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
+<p><font size="2">This documentation is part of the
+<a href="http://www.rsyslog.com/">rsyslog</a>
+project.<br>
+Copyright&nbsp;� 2008 by <a href="http://www.gerhards.net/rainer">Rainer
+Gerhards</a> and
+<a href="http://www.adiscon.com/">Adiscon</a>.
+Released under the GNU GPL version 3 or higher.</font></p>
+</body></html>
diff --git a/doc/imuxsock.html b/doc/imuxsock.html
index ee367dbc..77491992 100644
--- a/doc/imuxsock.html
+++ b/doc/imuxsock.html
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html><head>
-<meta http-equiv="Content-Language" content="en"><title>Unix Socket Input</title>
-
+<meta http-equiv="Content-Language" content="en">
+<title>Unix Socket Input</title>
 </head>
 <body>
 <h1>Unix Socket Input</h1>
@@ -9,31 +9,65 @@
 <p><b>Author: </b>Rainer Gerhards
 &lt;rgerhards@adiscon.com&gt;</p>
 <p><b>Description</b>:</p>
-<p>Provides the ability to accept syslog messages via local Unix
+<p><b>Provides the ability to accept syslog messages via local Unix
 sockets. Most importantly, this is the mechanism by which the syslog(3)
-call delivers syslog messages to rsyslogd. So you need to have this
+call delivers syslog messages to rsyslogd.</b> So you need to have this
 module loaded to read the system log socket and be able to process log
-messages from applications running on the local system.</p><p>Application-provided
-timestamps are ignored by default. This is needed, as some programs
-(e.g. sshd)&nbsp;log with inconsistent timezone information, what
+messages from applications running on the local system.</p>
+<p><b>Application-provided
+timestamps are ignored by default.</b> This is needed, as some programs
+(e.g. sshd) log with inconsistent timezone information, what
 messes up the local logs (which by default don't even contain time zone
 information). This seems to be consistent with what sysklogd did for
 the past four years. Alternate behaviour may be desirable if
 gateway-like processes send messages via the local log slot - in this
 case, it can be enabled via the
-$InputUnixListenSocketIgnoreMsgTimestamp and $SystemLogSocketIgnoreMsgTimestamp config directives</p><p><b>Configuration Directives</b>:</p>
+$InputUnixListenSocketIgnoreMsgTimestamp and $SystemLogSocketIgnoreMsgTimestamp config directives</p>
+<p><b>Unix log sockets can be flow-controlled.</b> That is, if processing queues fill up,
+the unix socket reader is blocked for a short while. This may be useful to prevent overruning
+the queues (which may cause exessive disk-io where it actually would not be needed). However,
+flow-controlling a log socket (and especially the system log socket) can lead to a very
+unresponsive system. As such, flow control is disabled by default. That means any log records
+are places as quickly as possible into the processing queues. If you would like to have
+flow control, you need to enable it via the $SystemLogSocketFlowControl and
+$InputUnixListenSocketFlowControl config directives. Just make sure you thought about
+the implications. Note that for many systems, turning on flow control does not hurt.
+<p><b>Configuration Directives</b>:</p>
 <ul>
-<li><span style="font-weight: bold;">$InputUnixListenSocketIgnoreMsgTimestamp</span> [<span style="font-weight: bold;">on</span>/off]<strong></strong><br>Ignore timestamps included in the message. Applies to the next socket being added.</li><li><span style="font-weight: bold;">$SystemLogSocketIgnoreMsgTimestamp</span> [<span style="font-weight: bold;">on</span>/off]<br>Ignore timestamps included in the messages, applies to messages received via the system log socket.</li><li><span style="font-weight: bold;">$OmitLocalLogging</span> (imuxsock) [on/<b>off</b>] --
-former -o option</li><li><span style="font-weight: bold;">$SystemLogSocketName</span> &lt;name-of-socket&gt; --
-former -p option</li><li><span style="font-weight: bold;">$AddUnixListenSocket</span> &lt;name-of-socket&gt; adds
-additional unix socket, default none -- former -a option</li></ul>
+<li><b>$InputUnixListenSocketIgnoreMsgTimestamp</b> [<b>on</b>/off]
+<br>Ignore timestamps included in the message. Applies to the next socket being added.</li>
+<li><b>$InputUnixListenSocketFlowControl</b> [on/<b>off</b>] - specifies if flow control should be applied
+to the next socket.</li>
+<li><b>$SystemLogSocketIgnoreMsgTimestamp</b> [<b>on</b>/off]<br>
+Ignore timestamps included in the messages, applies to messages received via the system log socket.</li>
+<li><b>$OmitLocalLogging</b> (imuxsock) [on/<b>off</b>] -- former -o option</li>
+<li><b>$SystemLogSocketName</b> &lt;name-of-socket&gt; -- former -p option</li>
+<li><b>$SystemLogFlowControl</b> [on/<b>off</b>] - specifies if flow control should be applied
+to the system log socket.</li>
+<li><b>$AddUnixListenSocket</b> &lt;name-of-socket&gt; adds additional unix socket, default none -- former -a option</li>
+<li><b>$InputUnixListenSocketHostName</b> &lt;hostname&gt; permits to override the hostname that
+shall be used inside messages taken from the <b>next</b> $AddUnixListenSocket socket. Note that
+the hostname must be specified before the $AddUnixListenSocket configuration directive, and it
+will only affect the next one and then automatically be reset. This functionality is provided so
+that the local hostname can be overridden in cases where that is desired.</li>
+</ul>
 <b>Caveats/Known Bugs:</b><br>
 <br>
 This documentation is sparse and incomplete.
 <p><b>Sample:</b></p>
 <p>The following sample is the minimum setup required to accept syslog messages from applications running on the local system.<br>
 </p>
-<textarea rows="15" cols="60">$ModLoad imuxsock # needs to be done just once
+<textarea rows="2" cols="70">$ModLoad imuxsock # needs to be done just once
+$SystemLogSocketFlowControl on # enable flow control (use if needed)
+</textarea>
+<p>The following sample is a configuration where rsyslogd pulls logs from two
+jails, and assigns different hostnames to each of the jails: </p>
+<textarea rows="6" cols="60">$ModLoad imuxsock # needs to be done just once
+
+$InputUnixListenSocketHostName jail1.example.net
+$AddUnixListenSocket /jail/1/dev/log
+$InputUnixListenSocketHostName jail2.example.net
+$AddUnixListenSocket /jail/2/dev/log
 </textarea>
 <p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>]
 [<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
@@ -44,4 +78,4 @@ Copyright � 2008 by <a href="http://www.gerhards.net/rainer">Rainer
 Gerhards</a> and
 <a href="http://www.adiscon.com/">Adiscon</a>.
 Released under the GNU GPL version 3 or higher.</font></p>
-</body></html>
-\ No newline at end of file
+</body></html>
diff --git a/doc/manual.html b/doc/manual.html
index cbb3477d..3e9d57a8 100644
--- a/doc/manual.html
+++ b/doc/manual.html
@@ -16,7 +16,7 @@ relay chains while at the same time being very easy to setup for the
 novice user. And as we know what enterprise users really need, there is
 also <a href="professional_support.html">professional
 rsyslog support</a> available directly from the source!</p>
-<p><b>This documentation is for version 3.20.0 (v3-stable branch) of rsyslog.</b>
+<p><b>This documentation is for version 3.21.7 (beta branch) of rsyslog.</b>
 Visit the <i> <a href="http://www.rsyslog.com/doc-status.html">rsyslog status page</a></i></b> to obtain current
 version information and project status.
 </p><p><b>If you like rsyslog, you might
@@ -33,19 +33,14 @@ the links below for the</b><br></p><ul>
 
 <li><a href="troubleshoot.html">troubleshooting rsyslog problems</a></li>
 <li><a href="rsyslog_conf.html">configuration file syntax (rsyslog.conf)</a></li>
-<li> <a href="property_replacer.html">property
-replacer, an important core component</a></li>
-<li>a commented <a href="sample.conf.html">sample
-rsyslog.conf</a>
-</li>
+<li> <a href="property_replacer.html">property replacer, an important core component</a></li>
+<li>a commented <a href="sample.conf.html">sample rsyslog.conf</a></li>
 <li><a href="bugs.html">rsyslog bug list</a></li>
-<li><a href="rsyslog_packages.html"> rsyslog
-packages</a></li>
+<li><a href="rsyslog_packages.html"> rsyslog packages</a></li>
 <li><a href="generic_design.html">backgrounder on
 generic syslog application design</a><!-- not good as it currently is ;) <li><a href="contributors.html">contributor &quot;Hall of Fame&quot;</a>--></li>
-<li><a href="modules.html">description of rsyslog
-modules</a></li><li><a href="man_rsyslogd.html">rsyslogd man page</a>
-(heavily outdated)</li>
+<li><a href="modules.html">description of rsyslog modules</a></li>
+<li><a href="man_rsyslogd.html">rsyslogd man page</a> (heavily outdated)</li>
 </ul>
 <p><b>We have some in-depth papers on</b></p>
 <ul>
@@ -75,8 +70,7 @@ the world needs another syslogd</a>".</p>
 <p>Documentation is added continuously. Please note that the
 documentation here
 matches only the current version of rsyslog. If you use an older
-version, be sure
-to use the doc that came with it.</p>
+version, be sure to use the doc that came with it.</p>
 <p><b>You can also browse the following online resources:</b></p>
 <ul>
 <li>the <a href="http://wiki.rsyslog.com/">rsyslog
@@ -101,4 +95,6 @@ If you would like to use rsyslog source code inside your open source project, yo
 any restriction as long as your license is GPLv3 compatible. If your license is incompatible to GPLv3,
 you may even be still permitted to use rsyslog source code. However, then you need to look at the way
 <a href="licensing.html">rsyslog is licensed</a>.</p>
+<p>Feedback is always welcome, but if you have a support question, please do not
+mail Rainer directly (<a href="free_support.html">why not?</a>).
 </body></html>
diff --git a/doc/ommail.html b/doc/ommail.html
index 62ded6d0..c18cf3f8 100644
--- a/doc/ommail.html
+++ b/doc/ommail.html
@@ -50,7 +50,10 @@ standard SMTP port.</li>
 <li><span style="font-weight: bold;">$ActionMailFrom</span><br>
 The email address used as the senders address. There is no default.</li>
 <li><span style="font-weight: bold;">$ActionMailTo</span><br>
-The recipients email address. There is no default.</li>
+The recipient email addresses. There is no default. To specify multiple
+recpients, repeat this directive as often as needed. Note: <b>This directive
+must be specified for each new action and is automatically reset.</b> 
+[Multiple recipients are supported for 3.21.2 and above.]</li>
 <li><span style="font-weight: bold;">$ActionMailSubject</span><br>
 The name of the <span style="font-weight: bold;">template</span>
 to be used as the mail subject. If this is not specified, a more or
@@ -112,14 +115,28 @@ $ActionExecOnlyOnceEveryInterval 21600
 # the if ... then ... mailBody mus be on one line!
 if $msg contains 'hard disk fatal failure' then :ommail:;mailBody
 </textarea>
+<p>The sample below is the same, but sends mail to two recipients:</p>
+<textarea rows="15" cols="80">$ModLoad ommail
+$ActionMailSMTPServer mail.example.net
+$ActionMailFrom rsyslog@example.net
+$ActionMailTo operator@example.net
+$ActionMailTo admin@example.net
+$template mailSubject,"disk problem on %hostname%"
+$template mailBody,"RSYSLOG Alert\r\nmsg='%msg%'"
+$ActionMailSubject mailSubject
+# make sure we receive a mail only once in six
+# hours (21,600 seconds ;))
+$ActionExecOnlyOnceEveryInterval 21600
+# the if ... then ... mailBody mus be on one line!
+if $msg contains 'hard disk fatal failure' then :ommail:;mailBody
+</textarea>
 <p>A more advanced example plus a discussion on using the email feature
 inside a reliable system can be found in Rainer's blogpost
 "<a style="font-style: italic;" href="http://rgerhards.blogspot.com/2008/04/why-is-native-email-capability.html">Why
 is native email capability an advantage for a syslogd?</a>"
 <p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>]
 [<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
-<p><font size="2">This documentation is part of the
-<a href="http://www.rsyslog.com/">rsyslog</a>
+<p><font size="2">This documentation is part of the <a href="http://www.rsyslog.com/">rsyslog</a>
 project.<br>
 Copyright &copy; 2008 by <a href="http://www.gerhards.net/rainer">Rainer
 Gerhards</a> and
diff --git a/doc/property_replacer.html b/doc/property_replacer.html
index 367c8add..f666fb76 100644
--- a/doc/property_replacer.html
+++ b/doc/property_replacer.html
@@ -72,7 +72,7 @@ BSD syslogd. For example, when TAG is "named[12345]", programname is
 "syslog.info")</td>
 </tr>
 <tr>
-<td><span style="font-weight: bold;">iut</span></td>
+<td><b>iut</b></td>
 <td>the monitorware InfoUnitType - used when talking
 to a <a href="http://www.monitorware.com">MonitorWare</a>
 backend (also for <a href="http://www.phplogcon.org/">phpLogCon</a>)</td>
@@ -138,10 +138,26 @@ draft-ietf-syslog-protocol</td>
 draft-ietf-syslog-protocol</td>
 </tr>
 <tr>
-<td height="24"><b>msgid</b></td>
-<td height="24">The contents of the MSGID field from
+<td><b>msgid</b></td>
+<td>The contents of the MSGID field from
 IETF draft draft-ietf-syslog-protocol</td>
 </tr>
+<td><b>inputname</b></td>
+<td>The name of the input module that generated the
+message (e.g. "imuxsock", "imudp"). Note that not all modules
+necessarily provide this property. If not provided, it is an
+empty string. Also note that the input module may provide
+any value of its liking. Most importantly, it is <b>not</b>
+necessarily the module input name. Internal sources can also
+provide inputnames. Currently, "rsyslogd" is defined as inputname
+for messages internally generated by rsyslogd, for example startup
+and shutdown and error messages.
+This property is considered useful when trying to filter messages
+based on where they originated - e.g. locally generated messages
+("rsyslogd", "imuxsock", "imklog") should go to a different place
+than messages generated somewhere.
+</td>
+</tr>
 <tr>
 <td><b>$now</b></td>
 <td>The current date stamp in the format YYYY-MM-DD</td>
@@ -177,6 +193,11 @@ range from 0 to 3 (for the four quater hours that are in each hour)</td>
 <td><b>$minute</b></td>
 <td>The current minute (2-digit)</td>
 </tr>
+<tr>
+<td><b>$myhostname</b></td>
+<td>The name of the current host as it knows itself (probably useful
+for filtering in a generic way)</td>
+</tr>
 </tbody>
 </table>
 <p>Properties starting with a $-sign are so-called system
@@ -250,8 +271,30 @@ same example with semicolon as delimiter is "%msg:F,59:3%".</p>
 <p>Please note that the special characters "F" and "R" are
 case-sensitive. Only upper case works, lower case will return an error.
 There are no white spaces permitted inside the sequence (that will lead
-to error messages and will NOT provide the intended result).<br>
+to error messages and will NOT provide the intended result).</p>
+<p>Each occurence of the field delimiter starts a new field. However, 
+if you add a plus sign ("+") after the field delimiter, multiple
+delimiters, one  immediately after the others, are treated as separate
+fields. This can be useful in cases where the syslog message contains
+such sequences. A frequent case may be with code that is written as
+follows:</p>
+<code><pre>
+int n, m;
+...
+syslog(LOG_ERR, "%d test %6d", n, m);
+</pre></code>
+<p>This will result into things like this in syslog messages:
+"1 test&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2", 
+"1 test&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;23", 
+"1 test&nbsp;&nbsp;234567" 
+<p>As you can see, the fields are delimited by space characters, but
+their exact number is unknown. They can properly be extracted as follows:
+<p>
+"%msg:F,32:2%" to "%msg:F,32+:2%".
+<p>This feature was suggested by Zhuang Yuyao and implemented by him.
+It is modeled after perl compatible regular expressions.
 </p>
+
 <h2>Property Options</h2>
 <b><code>property options</code></b> are
 case-insensitive. Currently, the following options are defined:
diff --git a/doc/rsyslog_conf.html b/doc/rsyslog_conf.html
index a74f2d44..7cd40cb7 100644
--- a/doc/rsyslog_conf.html
+++ b/doc/rsyslog_conf.html
@@ -79,8 +79,33 @@ default, it is usually well-chosen and applicable in most cases.</p>
 execute action only if the last execute is at last
 &lt;seconds&gt; seconds in the past (more info in <a href="ommail.html">ommail</a>,
 but may be used with any action)</li>
-<li>$ActionFileDefaultTemplate [templateName] - sets a new
-default template for file actions</li>
+<li><i><b>$ActionExecOnlyEveryNthTime</b> &lt;number&gt;</i> - If configured, the next action will
+only be executed every n-th time. For example, if configured to 3, the first two messages
+that go into the action will be dropped, the 3rd will actually cause the action to execute,
+the 4th and 5th will be dropped, the 6th executed under the action, ... and so on. Note: 
+this setting is automatically re-set when the actual action is defined.</li>
+<li><i><b>$ActionExecOnlyEveryNthTimeTimeout</b> &lt;number-of-seconds&gt;</i> - has a meaning only if
+$ActionExecOnlyEveryNthTime is also configured for the same action. If so, the timeout
+setting specifies after which period the counting of "previous actions" expires and
+a new action count is begun. Specify 0 (the default) to disable timeouts.
+<br>
+<i>Why is this option needed?</i> Consider this case: a message comes in at, eg., 10am. That's
+count 1. Then, nothing happens for the next 10 hours. At 8pm, the next
+one occurs. That's count 2. Another 5 hours later, the next message
+occurs, bringing the total count to 3. Thus, this message now triggers
+the rule.
+<br>
+The question is if this is desired behavior? Or should the rule only be
+triggered if the messages occur within an e.g. 20 minute window? If the
+later is the case, you need a
+<br>
+$ActionExecOnlyEveryNthTimeTimeout 1200
+<br>
+This directive will timeout previous messages seen if they are older
+than 20 minutes. In the example above, the count would now be always 1
+and consequently no rule would ever be triggered.
+
+<li>$ActionFileDefaultTemplate [templateName] - sets a new default template for file actions</li>
 <li>$ActionFileEnableSync [on/<span style="font-weight: bold;">off</span>] - enables file
 syncing capability of omfile</li>
 <li>$ActionForwardDefaultTemplate [templateName] - sets a new
@@ -142,6 +167,7 @@ default 60000 (1 minute)]</li>
 <li><a href="rsconf1_droptrailinglfonreception.html">$DropTrailingLFOnReception</a></li>
 <li><a href="rsconf1_dynafilecachesize.html">$DynaFileCacheSize</a></li>
 <li><a href="rsconf1_escapecontrolcharactersonreceive.html">$EscapeControlCharactersOnReceive</a></li>
+<li>$ErrorMessagesToStderr [<b>on</b>|off] - direct rsyslogd error message to stderr (in addition to other targets)</li>
 <li><a href="rsconf1_failonchownfailure.html">$FailOnChownFailure</a></li>
 <li><a href="rsconf1_filecreatemode.html">$FileCreateMode</a></li>
 <li><a href="rsconf1_filegroup.html">$FileGroup</a></li>
@@ -182,10 +208,30 @@ default 60000 (1 minute)]</li>
 </li>
 <li>$MainMsgQueueWorkerThreads &lt;number&gt;, num
 worker threads, default 1, recommended 1</li>
-<li>$MainMsgQueueWorkerThreadMinumumMessages
-&lt;number&gt;, default 100</li>
-<li><a href="rsconf1_markmessageperiod.html">$MarkMessagePeriod</a>
-(immark)</li>
+<li>$MainMsgQueueWorkerThreadMinumumMessages &lt;number&gt;, default 100</li>
+<li><a href="rsconf1_markmessageperiod.html">$MarkMessagePeriod</a> (immark)</li>
+<li><b><i>$MaxMessageSize</i></b> &lt;size_nbr&gt;, default 2k - allows to specify maximum supported message size
+(both for sending and receiving). The default
+should be sufficient for almost all cases. Do not set this below 1k, as it would cause
+interoperability problems with other syslog implementations.<br>
+Change the setting to e.g. 32768 if you would like to
+support large message sizes for IHE (32k is the current maximum
+needed for IHE). I was initially tempted to set the default to 32k,
+but there is a some memory footprint with the current
+implementation in rsyslog.
+<br>If you intend to receive Windows Event Log data (e.g. via
+<a href="http://www.eventreporter.com/">EventReporter</a>), you might want to 
+increase this number to an even higher value, as event
+log messages can be very lengthy ("$MaxMessageSize 64k" is not a bad idea).
+Note: testing showed that 4k seems to be
+the typical maximum for <b>UDP</b> based syslog. This is an IP stack
+restriction. Not always ... but very often. If you go beyond
+that value, be sure to test that rsyslogd actually does what
+you think it should do ;) It is highly suggested to use a TCP based transport
+instead of UDP (plain TCP syslog, RELP). This resolves the UDP stack size restrictions.
+<br>Note that 2k, the current default, is the smallest size that must be
+supported in order to be compliant to the upcoming new syslog RFC series.
+</li>
 <li><a href="rsconf1_moddir.html">$ModDir</a></li>
 <li><a href="rsconf1_modload.html">$ModLoad</a></li>
 <li><a href="rsconf1_repeatedmsgreduction.html">$RepeatedMsgReduction</a></li>
@@ -787,7 +833,7 @@ administration needs.<br>
 forward messages it has received from the network to another host.
 Specify the "-h" option to enable this.</b></p>
 <p>To forward messages to another host, prepend the hostname with
-the at sign ("@").&nbsp; A single at sign means that messages will
+the at sign ("@"). A single at sign means that messages will
 be forwarded via UDP protocol (the standard for syslog). If you prepend
 two at signs ("@@"), the messages will be transmitted via TCP. Please
 note that plain TCP based syslog is not officially standardized, but
diff --git a/doc/rsyslog_ng_comparison.html b/doc/rsyslog_ng_comparison.html
index 6d14d933..2f383f78 100644
--- a/doc/rsyslog_ng_comparison.html
+++ b/doc/rsyslog_ng_comparison.html
@@ -209,10 +209,8 @@ priority</td>
 <td></td>
 </tr>
 <tr>
-<td valign="top">ability to filter on any other
-message
-field not mentioned above
-(including substrings and the like)</td>
+<td valign="top">ability to filter on any other message
+field not mentioned above (including substrings and the like)</td>
 <td valign="top">yes</td>
 <td valign="top">no</td>
 </tr>
@@ -248,6 +246,12 @@ based on filters</td>
 <td></td>
 </tr>
 <tr>
+<td valign="top">ability to filter out messages based on sequence of appearing</td>
+<td valign="top">yes (starting with 3.21.3)</td>
+<td valign="top">no</td>
+<td></td>
+</tr>
+<tr>
 <td valign="top">powerful BSD-style hostname and
 program name blocks for easy multi-host support</td>
 <td valign="top">yes</td>
@@ -428,17 +432,9 @@ including ability to present channel and priority as visible log data</td>
 <td valign="top">yes</td>
 <td valign="top">yes</td>
 </tr>
-<<<<<<< HEAD:doc/rsyslog_ng_comparison.html
-<tr>
-<td valign="top">native ability to send mail messages</td>
-<td valign="top">yes (<a href="ommail.html">ommail</a>,
-introduced in 3.17.0)</td>
-<td valign="top">not sure...</td>
-=======
 <tr><td valign="top">native ability to send mail messages</td>
 <td valign="top">yes (<a href="ommail.html">ommail</a>, introduced in 3.17.0)</td>
 <td valign="top">no (only via piped external process)</td>
->>>>>>> 3f2856b4b5010dfcaa720b292dc3a655e7b9f6da:doc/rsyslog_ng_comparison.html
 </tr>
 <tr>
 <td valign="top">good timestamp format control; at a
diff --git a/doc/status.html b/doc/status.html
index 90932fca..5c8409ec 100644
--- a/doc/status.html
+++ b/doc/status.html
@@ -2,24 +2,22 @@
 <html><head><title>rsyslog status page</title></head>
 <body>
 <h2>rsyslog status page</h2>
-<p>This page reflects the status as of 2008-07-15.</p>
+<p>This page reflects the status as of 2008-10-22.</p>
 <h2>Current Releases</h2>
 
-<!-- no devel at this time!
-<p><b>development:</b> 3.19.9 [2008-07-07] -
-<a href="http://www.rsyslog.com/Article250.phtml">change log</a> -
-<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-117.phtml">download</a>
--->
+<p><b>development:</b> 3.21.6 [2008-10-22] -
+<a href="http://www.rsyslog.com/Article292.phtml">change log</a> -
+<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-135.phtml">download</a>
 
-<br><b>beta:</b> 3.19.10 [2008-07-15] -
-<a href="http://www.rsyslog.com/Article256.phtml">change log</a> -
-<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-109.phtml">download</a></p>
+<br><b>beta:</b> 3.19.12 [2008-10-16] -
+<a href="http://www.rsyslog.com/Article283.phtml">change log</a> -
+<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-134.phtml">download</a></p>
 
-<p><b>v3 stable:</b> 3.18.0 [2008-07-11] - <a href="http://www.rsyslog.com/Article254.phtml">change log</a> -
-<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-120.phtml">download</a>
+<p><b>v3 stable:</b> 3.18.5 [2008-10-09] - <a href="http://www.rsyslog.com/Article281.phtml">change log</a> -
+<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-133.phtml">download</a>
 
-<br><b>v2 stable:</b> 2.0.5 [2008-05-15] - <a href="http://www.rsyslog.com/Article226.phtml">change log</a> -
-<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-104.phtml">download</a>
+<br><b>v2 stable:</b> 2.0.6 [2008-08-07] - <a href="http://www.rsyslog.com/Article266.phtml">change log</a> -
+<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-125.phtml">download</a>
 <br>v0 and v1 are deprecated and no longer supported. If you absolutely do not like to
 upgrade, you may consider purchasing a
 <a href="professional_support.html">commercial rsyslog support package</a>. Just let us point
diff --git a/doc/syslog-protocol.html b/doc/syslog_protocol.html
index 72de5c27..72de5c27 100644
--- a/doc/syslog-protocol.html
+++ b/doc/syslog_protocol.html
diff --git a/doc/troubleshoot.html b/doc/troubleshoot.html
index b1e9c4ae..e655c2ef 100644
--- a/doc/troubleshoot.html
+++ b/doc/troubleshoot.html
@@ -12,10 +12,22 @@ the most recent development version. However, there is a version-specific
 doc set in each tarball. If you installed rsyslog from a package, there usually
 is a rsyslog-doc package, that often needs to be installed separately.
 <li>The <a href="http://wiki.rsyslog.com">rsyslog wiki</a> provides user tips and experiences.
-<li>A common trouble source are <a href="syslog_parsing.html">ill-formed syslog messages</a>, which
-lead to to all sorts of interesting problems, including malformed hostnames and dates. Read the quoted
-guide to find relief.
+<li>Check <a href="http://bugzilla.adiscon.com">the bugzilla</a> to see if your problem is a known
+(and even fixed ;)) bug.
 </ul>
+<p><b>Malformed Messages and Message Properties</b>
+<p>A common trouble source are <a href="syslog_parsing.html">ill-formed syslog messages</a>, which
+lead to to all sorts of interesting problems, including malformed hostnames and dates.
+Read the quoted guide to find relief.
+<p><b>Configuration Problems</b>
+<p>Rsyslog 3.21.1 and above has been enhanced to support extended configuration checking.
+It offers a special command line switch (-N1) that puts it into "config verfication mode".
+In that mode, it interprets and check the configuration file, but does not startup. This
+mode can be used in parallel to a running instance of rsyslogd.
+<p>To enable it, run rsyslog interactively as follows:
+<p><b><i>/path/to/rsyslogd -f/path/to/config-file -N1</i></b>
+<p>You should also specify other options you usually give (like -c3 and whatever else).
+Any problems experienced are reported to stderr [aka "your screen" (if not redirected)].
 <p><b>Asking for Help</b>
 <p>If you can't find the answer yourself, you should look at these places for
 community help.
@@ -26,6 +38,54 @@ the preferred method of obtaining support.
 This is a low-volume list which occasional gets traffic spikes.
 The mailing list is probably a good place for complex questions.
 </ul>
+<p><b>Debug Log</b>
+<p>If you ask for help, there are chances that we need to ask for an rsyslog debug log.
+The debug log is a detailled report of what rsyslog does during processing. As such, it may
+even be useful for your very own troubleshooting. People have seen things inside their debug
+log that enabled them to find problems they did not see before. So having a look at the
+debug log, even before asking for help, may be useful.
+<p>Note that the debug log contains most of those things we consider useful. This is a lot
+of information, but may still be too few. So it sometimes may happen that you will be asked
+to run a specific version which has additional debug output. Also, we revise from time to
+time what is worth putting into the standard debug log. As such, log content may change
+from version to version. We do not guarantee any specific debug log contents, so do not
+rely on that. The amount of debug logging can also be controlled via some environment
+options. Please see <a href="debug.html">debugging support</a> for further details.
+<p>In general, it is advisable to run rsyslogd in the foreground to obtain the log.
+To do so, make sure you know which options are usually used when you start rsyslogd
+as a background daemon. Let's assume "-c3" is the only option used. Then, do the following:
+<ul>
+<li>make sure rsyslogd as a daemon is stopped (verify with ps -ef|grep rsyslogd)
+<li>make sure you have a console session with root permissions
+<li>run rsyslogd interactively: /sbin/rsyslogd ..your options.. -dn &gt; logfile
+<br>where "your options" is what you usually use. /sbin/rsyslogd is the full path
+to the rsyslogd binary (location different depending on distro).
+In our case, the command would be
+<br>/sbin/rsyslogd -c3 -dn &gt; logfile
+<li>press ctrl-C when you have sufficient data (e.g. a device logged a record)
+<br><b>NOTE: rsyslogd will NOT stop automatically - you need to ctrl-c out of it!</b>
+<li>Once you have done all that, you can review logfile. It contains the debug output.
+<li>When you are done, make sure you re-enable (and start) the background daemon!
+</ul>
+<p>If you need to submit the logfile, you may want to check if it contains any
+passwords or other sensitive data. If it does, you can change it to some <b>consistent</b>
+meaningless value. <b>Do not delete the lines</b>, as this renders the debug log
+unusable (and makes Rainer quite angry for wasted time, aka significantly reduces the chance
+he will remain motivated to look at your problem ;)). For the same reason, make sure
+whatever you change is change consistently. Really!
+<p>Debug log file can get quite large. Before submitting them, it is a good idea to zip them.
+Rainer has handled files of around 1 to 2 GB. If your's is larger ask before submitting. Often, 
+it is sufficient to submit the first 2,000 lines of the log file and around another 1,000 around
+the area where you see a problem. Also,
+ask you can submit a file via private mail. Private mail is usually a good way to go for large files
+or files with sensitive content. However, do NOT send anything sensitive that you do not want
+the outside to be known. While Rainer so far made effort no to leak any sensitive information,
+there is no guarantee that doesn't happen. If you need a guarantee, you are probably a
+candidate for a <a href="professional_support.html">commercial support contract</a>. Free support
+comes without any guarantees, include no guarantee on confidentiality
+[aka "we don't want to be sued for work were are not even paid for ;)].
+<b>So if you submit debug logs, do so at your sole risk</b>. By submitting them, you accept
+this policy.
 <p>[<a href="manual.html">manual index</a>]
 [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
 <p><font size="2">This documentation is part of the
author	Rainer Gerhards <rgerhards@adiscon.com>	2008-11-11 12:54:44 +0100
committer	Rainer Gerhards <rgerhards@adiscon.com>	2008-11-11 12:54:44 +0100
commit	05bd696ebb7766f33b3ae176b841bcecb0bfedfc (patch)
tree	99437759863ee4b25174f49aa69807c207176a76 /doc
parent	9048c16d90177a0dfa4131266ae73f029a5923c8 (diff)
parent	ba201a941435bc5fec2c333155e1a8e16c4a9c05 (diff)
download	rsyslog-05bd696ebb7766f33b3ae176b841bcecb0bfedfc.tar.gz rsyslog-05bd696ebb7766f33b3ae176b841bcecb0bfedfc.tar.xz rsyslog-05bd696ebb7766f33b3ae176b841bcecb0bfedfc.zip