- enhanced file monitor doc

- implemented $InputFilePollInterval config directive

1 files changed, 84 insertions, 35 deletions

diff --git a/doc/imfile.html b/doc/imfile.html
index 6942b366..15ace7c1 100644
--- a/doc/imfile.html
+++ b/doc/imfile.html
@@ -13,46 +13,95 @@
 <p>Provides the ability to convert any standard text file into
 a syslog message. A standard
 text file is a file consisting of printable characters with lines
-being&nbsp;delimited by LF.</p><p>The
-file is read line-by-line and any line read is passed to rsyslog's rule
-engine. The rule engine applies filter conditons and selects which
-actions needs to be carried out.</p><p>As new lines are written they
-are taken from the file and processed. Please note that this happens
-based on a polling interval and not immediately. The file monitor
-support file rotation. To fully work, rsyslogd must run while the file
-is rotated. Then, any remaining lines from the old file are read and
-processed and when done with that, the new file is being processed from
-the beginning. If rsyslogd is stopped during rotation, the new file is
-read, but any not-yet-reported lines from the previous file can no
-longer be obtained.</p><p>When rsyslogd is stopped while monitoring a
-text file, it records the last processed location and continues to work
-from there upon restart. So no data is lost during a restart (except,
-as noted above, if the file is rotated just in this very moment).</p><p>Currently,
-the file must have a fixed name and location (directory). It is planned
-to add support for dynamically generating file names in the future.</p><p>Multiple files may be monitored by specifying $InputRunFileMonitor multiple times.
+being&nbsp;delimited by LF.</p>
+<p>The file is read line-by-line and any line read is passed to
+rsyslog's rule engine. The rule engine applies filter conditons and
+selects which actions needs to be carried out.</p>
+<p>As new lines are written they are taken from the file and
+processed. Please note that this happens based on a polling interval
+and not immediately. The file monitor support file rotation. To fully
+work, rsyslogd must run while the file is rotated. Then, any remaining
+lines from the old file are read and processed and when done with that,
+the new file is being processed from the beginning. If rsyslogd is
+stopped during rotation, the new file is read, but any not-yet-reported
+lines from the previous file can no longer be obtained.</p>
+<p>When rsyslogd is stopped while monitoring a text file, it
+records the last processed location and continues to work from there
+upon restart. So no data is lost during a restart (except, as noted
+above, if the file is rotated just in this very moment).</p>
+<p>Currently, the file must have a fixed name and location
+(directory). It is planned to add support for dynamically generating
+file names in the future.</p>
+<p>Multiple files may be monitored by specifying
+$InputRunFileMonitor multiple times.
 </p>
 <p><b>Configuration Directives</b>:</p>
 <ul>
 <li><strong>$InputFileName&nbsp;/path/to/file</strong><br>
-The file being monitored. So far, this must be an absolute name (no macros or templates)</li><li><span style="font-weight: bold;">$InputFileTag tag:</span><br>The
-tag to be used for messages that originate from this file. If you would
-like to see the colon after the tag, you need to specify it here (as
-shown above).</li><li><span style="font-weight: bold;">$InputFileStateFile &lt;name-of-state-file&gt;</span><br>Rsyslog
-must keep track of which parts of the to be monitored file it already
-processed. This is done in the state file. This file always is created
-in the rsyslog working directory (configurable via $WorkDirectory). Be
-careful to use unique names for different files being monitored. If
-there are duplicates, all sorts of "interesting" things may happen.
-Rsyslog currently does not check if a name is specified multiple times.</li><li><span style="font-weight: bold;">$InputRunFileMonitor</span><br>This <span style="font-weight: bold;">activates</span> the current monitor. It has no parameters. If you forget this directive, no file monitoring will take place.
-</li></ul><b>Caveats/Known Bugs:</b>
+The file being monitored. So far, this must be an absolute name (no
+macros or templates)</li>
+<li><span style="font-weight: bold;">$InputFileTag
+tag:</span><br>
+The tag to be used for messages that originate from this file. If you
+would like to see the colon after the tag, you need to specify it here
+(as shown above).</li>
+<li><span style="font-weight: bold;">$InputFileStateFile
+&lt;name-of-state-file&gt;</span><br>
+Rsyslog must keep track of which parts of the to be monitored file it
+already processed. This is done in the state file. This file always is
+created in the rsyslog working directory (configurable via
+$WorkDirectory). Be careful to use unique names for different files
+being monitored. If there are duplicates, all sorts of "interesting"
+things may happen. Rsyslog currently does not check if a name is
+specified multiple times.</li>
+<li><span style="font-weight: bold;">$InputRunFileMonitor</span><br>
+This <span style="font-weight: bold;">activates</span>
+the current monitor. It has no parameters. If you forget this
+directive, no file monitoring will take place.</li>
+<li><span style="font-weight: bold;">$InputFilePollInterval
+seconds</span><br>
+This is a global setting. It specifies how often files are to be polled
+for new data. The time specified is in seconds. The <span style="font-weight: bold;">default value</span> is 10 seconds. Please note that future
+releases of imfile may support per-file polling intervals, but
+currently this is not the case. If multiple $InputFilePollInterval
+statements are present in rsyslog.conf, only the last one is used.<br>
+A short poll interval provides more rapid message forwarding, but
+requires more system ressources. While it is possible, we stongly
+recommend not to set the polling interval to 0 seconds. That will make
+rsyslogd become a CPU hog, taking up considerable ressources. It is
+supported, however, for the few very unusual situations where this
+level may be needed. Even if you need quick response, 1 seconds should
+be well enough. Please note that imfile keeps reading files as long as
+there is any data in them. So a "polling sleep" will only happen when
+nothing is left to be processed.</li>
+</ul>
+<b>Caveats/Known Bugs:</b>
+<p>So far, only 100 files can be monitored. If more are needed,
+the source needs to be patched. See define MAX_INPUT_FILES in imfile.c
+</p>
 <p><b>Sample:</b></p>
-<p>The following sample monitors a single file.<br></p>
-<textarea rows="10" cols="60">
-ModLoad imfile.so
-$InputFileName /path/to/file
-$InputFileTag tag:
-$InputFileStateFile file-in-workdir to keep status in
-$InputRunFileMonitor </textarea>
+<p>The following sample monitors two files. If you need just one,
+remove the second one. If you need more, add them according to the
+sample ;). This code must be placed in /etc/rsyslog.conf (or wherever
+your distro puts rsyslog's config files).<br>
+</p>
+<textarea rows="15" cols="60">$ModLoad imfile.so #
+needs to be done just once
+# File 1
+$InputFileName /path/to/file1
+$InputFileTag tag1:
+$InputFileStateFile stat-file1
+$InputRunFileMonitor
+# File 2
+$InputFileName /path/to/file2
+$InputFileTag tag2:
+$InputFileStateFile stat-file2
+$InputRunFileMonitor
+# ... and so on ...
+#
+# check for new lines every 10 seconds
+$InputFilePollingInterval 10
+</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>
 <p><font size="2">This documentation is part of the