From ad50194ceb52bcf45566f98b801d72163a005718 Mon Sep 17 00:00:00 2001
From: Rainer Gerhards <rgerhards@adiscon.com>
Date: Tue, 17 Sep 2013 10:08:03 +0200
Subject: doc: bugfixes & enhancements in omfile doc

---
 doc/omfile.html | 43 ++++++++++++++++++++++++++-----------------
 1 file changed, 26 insertions(+), 17 deletions(-)

diff --git a/doc/omfile.html b/doc/omfile.html
index 72320921..c5697119 100644
--- a/doc/omfile.html
+++ b/doc/omfile.html
@@ -11,19 +11,30 @@
 <p><b>Author: </b>Rainer Gerhards &lt;rgergards@adiscon.com&gt;</p>
 <p><b>Description</b>:</p>
 <p>The omfile plug-in provides the core functionality of writing messages to files residing inside the local file system (which may actually be remote if methods like NFS are used). Both files named with static names as well files with names based on message content are supported by this module. It is a built-in module that does not need to be loaded. </p>
-<p>&nbsp;</p>
 
 <p><b>Module Parameters</b>:</p>
 <ul>
 	<li><strong>Template </strong>[templateName]<br>
-	sets a new default template for file actions.<br></li>
+	Set the default template to be used if an action is not
+	configured to use a specific template.<br></li>
 	
 </ul>
 <p>&nbsp;</p>
 <p><b>Action Parameters</b>:</p>
 <ul>
-	<li><strong>DynaFileCacheSize </strong>(not mandatory, default will be used)<br>
-	Defines a template to be used for the output. <br></li><br>
+	<li><strong>Template </strong>[templateName]<br>
+	Sets the template to be used for this action. If not specified, the
+	default template is applied.<br></li><br>
+	
+	<li><strong>DynaFileCacheSize </strong>(not mandatory, default 10)<br>
+	Applies only if dynamic filenames are used.<br>
+	Specifies the number of DynaFiles that will be kept open. The default is
+	10. Note that this is a per-action value, so if you have multiple
+	dynafile actions, each of them have their individual caches (which means
+	the numbers sum up). Ideally, the cache size exactly matches the
+	need. You can use <a href="impstats.html">impstats</a> to tune this
+	value. Note that a too-low cache size can be a very considerable 
+	performance bottleneck.<br></li><br>
 
 	<li><strong>ZipLevel </strong>0..9 [default 0]<br>
 	if greater 0, turns on gzip compression of the output file. The higher the number, the better the compression, but also the more CPU is required for zipping.<br></li><br>
@@ -39,7 +50,8 @@
 	</li><br>
 
 	<li><strong>FlushInterval </strong>(not mandatory, default will be used)<br>
-	Defines a template to be used for the output. <br></li><br>
+	Defines, in seconds, the interval after which unwritten data is
+	flushed.<br></li><br>
 
 	<li><strong>ASyncWriting </strong>on/off [default off]<br>
 	if turned on, the files will be written in asynchronous mode via a separate thread. In that case, double buffers will be used so that one buffer can be filled while the other buffer is being written. Note that in order to enable FlushInterval, AsyncWriting must be set to "on". Otherwise, the flush interval will be ignored. Also note that when FlushOnTXEnd is "on" but AsyncWriting is off, output will only be written when the buffer is full. This may take several hours, or even require a rsyslog shutdown. However, a buffer flush can be forced in that case by sending rsyslogd a HUP signal. <br></li><br>
@@ -62,12 +74,12 @@
 	<li><strong>FileGroup </strong><br>
 	Set the group for files newly created. Please note that this setting does not affect the group of files already existing. The parameter is a group name, for which the groupid is obtained by rsyslogd during startup processing. Interim changes to the user mapping are not detected.<br></li><br>
 
-	<li><strong>DirCreateMode </strong>[defaul 0700]<br>
-	This is the same as $FileCreateMode, but for directories automatically generated.<br></li><br>
-
 	<li><strong>FileCreateMode </strong>[default 0644]<br>
 	The FileCreateMode directive allows to specify the creation mode with which rsyslogd creates new files. If not specified, the value 0644 is used (which retains backward-compatibility with earlier releases). The value given must always be a 4-digit octal number, with the initial digit being zero. <br>Please note that the actual permission depend on rsyslogd's process umask. If in doubt, use "$umask 0000" right at the beginning of the configuration file to remove any restrictions. <br>FileCreateMode may be specified multiple times. If so, it specifies the creation mode for all selector lines that follow until the next $FileCreateMode directive. Order of lines is vitally important.<br></li><br>
 
+	<li><strong>DirCreateMode </strong>[defaul 0700]<br>
+	This is the same as FileCreateMode, but for directories automatically generated.<br></li><br>
+
 	<li><strong>FailOnCHOwnFailure </strong>on/off [default on]<br>
 	This option modifies behaviour of file creation. If different owners or groups are specified for new files or directories and rsyslogd fails to set these new owners or groups, it will log an error and NOT write to the file in question if that option is set to "on". If it is set to "off", the error will be ignored and processing continues. Keep in mind, that the files in this case may be (in)accessible by people who should not have permission. The default is "on".<br></li><br>
 
@@ -75,7 +87,8 @@
 	create directories on an as-needed basis<br></li><br>
 
 	<li><strong>Sync </strong>on/off [default off]<br>
-	enables file syncing capability of omfile.<br></li><br>
+	enables file syncing capability of omfile. Note that this causes
+	an enormous performance hit if enabled.<br></li><br>
 
 	<li><strong>File </strong><br>
 	If the file already exists, new data is appended to it. Existing data is not truncated. If the file does not already exist, it is created. Files are kept open as long as rsyslogd is active. This conflicts with external log file rotation. In order to close a file after rotation, send rsyslogd a HUP signal after the file has been rotated away. <br></li><br>
@@ -93,9 +106,6 @@
 	there only is one provider called
 	"<a href="cryprov_gcry.html">gcry</a>".<br></li><br>
 
-	<li><strong>Template </strong>[templateName]<br>
-	sets a new default template for file actions.<br></li><br>
-	
 </ul>
 <p><b>Caveats/Known Bugs:</b></p>
 <ul>
@@ -119,11 +129,10 @@ unusable.
 </ul>
 <p><b>Sample:</b></p>
 <p>The following command writes all syslog messages into a file.</p>
-<textarea rows="5" cols="60">Module (load="builtin:omfile")
-*.* action(type="omfile" 
-           DirCreateMode="0700"
-           FileCreateMode="0644"
-           File="/var/log/messages")
+<textarea rows="5" cols="60">action(type="omfile" 
+       DirCreateMode="0700"
+       FileCreateMode="0644"
+       File="/var/log/messages")
 </textarea>
 
 <br><br>
-- 
cgit v1.2.3