From a8b583669a74dc053b0073531d8d3076779416a6 Mon Sep 17 00:00:00 2001
From: Rainer Gerhards <rgerhards@adiscon.com>
Date: Wed, 15 Jul 2009 11:12:28 +0200
Subject: CONFIG CHANGE: $HUPisRestart default is now "off".

We are doing this to support removal of restart-type HUP in v5.
Elaborate doc added to explain reasoning and actions to be taken.
---
 doc/Makefile.am              |  2 +-
 doc/manual.html              | 13 ++++----
 doc/rsyslog_conf_global.html | 12 ++++---
 doc/v4compatibility.html     | 77 ++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 93 insertions(+), 11 deletions(-)
 create mode 100644 doc/v4compatibility.html

(limited to 'doc')

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 62ec7500..3dfc8d3a 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -13,7 +13,6 @@ html_files = \
 	ipv6.html \
 	log_rotation_fix_size.html \
 	manual.html \
-	man_rsyslogd.html \
 	modules.html \
 	property_replacer.html \
 	rsyslog_ng_comparison.html \
@@ -91,6 +90,7 @@ html_files = \
 	rsconf1_resetconfigvariables.html \
 	rsconf1_umask.html \
 	v3compatibility.html \
+	v4compatibility.html \
 	im3195.html \
 	netstream.html \
 	ns_gtls.html \
diff --git a/doc/manual.html b/doc/manual.html
index 8a1e4fa0..d473f485 100644
--- a/doc/manual.html
+++ b/doc/manual.html
@@ -28,12 +28,13 @@ time - even a single mouse click helps. Learn <a href="how2help.html">how to hel
 Due to popular demand, there is now a <a href="rsyslog_ng_comparison.html">side-by-side comparison
 between rsyslog and syslog-ng</a>.</p>
 <p>If you are upgrading from rsyslog v2 or stock sysklogd,
-<a href="v3compatibility.html">be
-sure to read the rsyslog v3 compatibility document!</a> It will work even
+<a href="v3compatibility.html">be sure to read the rsyslog v3 compatibility document</a>,
+and if you are upgrading from v3, read the
+<a href="v4compatibility.html">rsyslog v4 compatibility document</a>.
+<p>Rsyslog will work even
 if you do not read the doc, but doing so will definitely improve your experience.</p>
-<p><span style="font-weight: bold;"></span><b>Follow
-the links below for the</b><br></p><ul>
-
+<p><b>Follow the links below for the</b></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="http://www.rsyslog.com/tool-regex">a regular expression checker/generator tool for rsyslog</a></li>
@@ -42,7 +43,7 @@ the links below for the</b><br></p><ul>
 <li><a href="bugs.html">rsyslog bug list</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>
+generic syslog application design</a>
 <li><a href="modules.html">description of rsyslog modules</a></li>
 </ul>
 <p><b>We have some in-depth papers on</b></p>
diff --git a/doc/rsyslog_conf_global.html b/doc/rsyslog_conf_global.html
index 03842758..1fe72c5f 100644
--- a/doc/rsyslog_conf_global.html
+++ b/doc/rsyslog_conf_global.html
@@ -129,11 +129,15 @@ our paper on <a href="multi_ruleset.html">using multiple rule sets in rsyslog</a
 <li><a href="rsconf1_gssforwardservicename.html">$GssForwardServiceName</a></li>
 <li><a href="rsconf1_gsslistenservicename.html">$GssListenServiceName</a></li>
 <li><a href="rsconf1_gssmode.html">$GssMode</a></li>
-<li>$HUPisRestart [<b>on</b>/off] - if set to on, a HUP is a full daemon restart. This means any queued messages are discarded (depending
+<li>$HUPisRestart [on/<b>off</b>] - if set to on, a HUP is a full daemon restart. This means any queued messages are discarded (depending
 on queue configuration, of course) all modules are unloaded and reloaded. This mode keeps compatible with sysklogd, but is
-not recommended for use with rsyslog. To do a full restart, simply stop and start the daemon. The default is "on" for
-compatibility reasons. If it is set to "off", a HUP will only close open files. This is a much quicker action and usually
-the only one that is needed e.g. for log rotation. <b>It is recommended to set the setting to "off".</b></li>
+not recommended for use with rsyslog. To do a full restart, simply stop and start the daemon. The default (since 4.5.1) is "off".
+If it is set to "off", a HUP will only close open files. This is a much quicker action and usually
+the only one that is needed e.g. for log rotation. <b>Restart-type HUPs (value "on") are depricated</b> 
+and will go away in rsyslog v5. So it is a good idea to change anything that needs it, now.
+Usually that should not be a big issue, as the restart-type HUP can easily be replaced by
+something along the lines of &quot;/etc/init.d/rsyslog restart&quot;.
+</li>
 <li><a href="rsconf1_includeconfig.html">$IncludeConfig</a></li><li>MainMsgQueueCheckpointInterval &lt;number&gt;</li>
 <li>$MainMsgQueueDequeueSlowdown &lt;number&gt; [number
 is timeout in <i> micro</i>seconds (1000000us is 1sec!),
diff --git a/doc/v4compatibility.html b/doc/v4compatibility.html
new file mode 100644
index 00000000..5d877af1
--- /dev/null
+++ b/doc/v4compatibility.html
@@ -0,0 +1,77 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head><title>Compatibility notes for rsyslog v4</title>
+</head>
+<body>
+<h1>Compatibility Notes for rsyslog v4</h1>
+<p><small><i>Written by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a>
+(2009-07-15)</i></small></p>
+<p>The changes introduced in rsyslog v4 are numerous, but not very intrusive.
+This document describes things to keep in mind when moving from v3 to v4. It 
+does not list enhancements nor does it talk about compatibility concerns introduced
+by v3 (for this, see the <a href="v3compatibility.html">rsyslog v3 compatibility notes</a>).
+<h2>HUP processing</h2>
+<p>With v3 and below, rsyslog used the traditional HUP behaviour. That meant that
+all output files are closed and the configuration file is re-read and the new configuration
+applied.
+<p>With a program as simple and static as sysklogd, this was not much of an issue. The
+most important config settings (like udp reception) of a traditional syslogd can not be
+modified via the configuration file. So a config file reload only meant setting up a new set of filters. It also didn't account as problem that while doing so messages may be lost - without
+any threading and queuing model, a traditional syslogd will potentially always loose
+messages, so it is irrelevant if this happens, too, during the short config re-read
+phase.
+<p>In rsyslog, things are quite different: the program is more or less a framework into
+which loadable modules are loaded as needed for a particular configuration. The software
+that will acutally be running is taylored via the config file. Thus, a re-read of
+the config file requires a full, very heavy restart, because the software acutally
+running with the new config can be totally different from what ran with the old config.
+<p>Consequently, the traditional HUP is a very heavy operation and may even cause some
+data loss because queues must be shut down, listeners stopped and so on. Some of these
+operations (depending on their configuration) involve intentional message loss. The operation
+also takes up a lot of system resources and needs quite some time (maybe seconds) to be
+completed. During this restart period, the syslog subsytem is not fully available.
+<p>From the software developer's point of view, the full restart done by a HUP is rather complex,
+especially if user-timeout limits set on action completion are taken into consideration (for
+those in the know: at the extreme ends this means we need to cancel threads as a last resort,
+but than we need to make sure that such cancellation does not happen at points where it
+would be fatal for a restart). A regular restart, where the process is actually terminated, is
+much less complex, because the operating system does a full cleanup after process termination,
+so rsyslogd does not need to take care for exotic cleanup cases and leave that to the OS.
+In the end result, restart-type HUPs clutter the code, increase complexity (read: add bugs)
+and cost performance.
+<p>On the contrary, a HUP is typically needed for log rotation, and the real desire is
+to close files. This is a non-disruptive and very lightweigth operation.
+<p>Many people have said that they are used to HUP the syslogd to apply configuration
+changes. This is true, but it is questionable if that really justifies all the cost that
+comes with it. After all, it is the difference between typing
+<pre>
+$ kill -HUP `cat /var/run/rsyslogd.pid`
+</pre>
+versus
+<pre>
+$ /etc/init.d/rsyslog restart
+</pre>
+Semantically, both is mostly the same thing. The only difference is that with the restart
+command rsyslogd can spit config error message to stderr, so that the user is able to see 
+any problems and fix them. With a HUP, we do not have access to stderr and thus can log
+error messages only to their configured destinations; exprience tells that most users
+will never find them there. What, by the way, is another strong argument against
+restarting rsyslogd by HUPing it.
+<p>So a restart via HUP is not strictly necessary
+and most other deamons require that a restart command is typed in if a restart is required.
+<p>Rsyslog will follow this paradigm in the next versions, resulting in many benefits. In v4,
+we provide some support for the old-style semantics. We introduced a setting $HUPisRestart
+which may be set to &quot;on&quot; (tradional, heavy operationg)
+or &quot;off&quot; (new, lightweight &quot;file close only&quot; operation).
+The initial versions had the default set to traditional behavior, but starting with 4.5.1
+we are now using the new behavior as the default.
+<p>Most importantly, <b>this may break some scripts</b>, but my sincere belief is that
+there are very few scripts that automatically <b>change</b> rsyslog's config and then do a
+HUP to reload it. Anyhow, if you have some of these, it may be a good idea to change
+them now instead of turning restart-type HUPs on. Other than that, one mainly needs
+to change the habit of how to restart rsyslog after a configuration change.
+<p><b>Please note that restart-type HUP is depricated and will go away in rsyslog v5.</b>
+So it is a good idea to become ready for the new version now and also enjoy some of the
+benefits of the &quot;real restart&quot;, like the better error-reporting capability.
+<p>Note that code complexity reduction (and thus performance improvement) needs the restart-type
+HUP code to be removed, so these changes can (and will) only happen in version 5.
+</body></html>
-- 
cgit