mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-19 22:00:42 +01:00
135 lines
6.5 KiB
HTML
135 lines
6.5 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html><head>
|
|
<meta http-equiv="Content-Language" content="en"><title>Text File Input Monitor</title></head>
|
|
<body>
|
|
<a href="rsyslog_conf_modules.html">back</a>
|
|
|
|
<h1>Text File Input Module</h1>
|
|
<p><b>Module Name: imfile</b></p>
|
|
<p><b>Author: </b>Rainer Gerhards
|
|
<rgerhards@adiscon.com></p>
|
|
<p><b>Description</b>:</p>
|
|
<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 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 /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
|
|
<name-of-state-file></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;">$InputFileFacility
|
|
facility</span><br>
|
|
The syslog facility to be assigned to lines read. Can be specified in
|
|
textual form (e.g. "local0", "local1", ...) or as numbers (e.g. 128 for
|
|
"local0"). Textual form is suggested. <span style="font-weight: bold;">Default</span> is
|
|
"local0".<span style="font-weight: bold;"></span></li>
|
|
<li><span style="font-weight: bold;">$InputFileSeverity</span><br>
|
|
The
|
|
syslog severity to be assigned to lines read. Can be specified in
|
|
textual form (e.g. "info", "warning", ...) or as numbers (e.g. 4 for
|
|
"info"). Textual form is suggested. <span style="font-weight: bold;">Default</span>
|
|
is "notice".</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>Powertop
|
|
users may want to notice that imfile utilizes polling. Thus, it is no
|
|
good citizen when it comes to conserving system power consumption. We
|
|
are currently evaluating to move to inotify(). However, there are a
|
|
number of subtle issues, which needs to be worked out first. We will
|
|
make the change as soon as we can. If you can afford it, we recommend
|
|
using a long polling interval in the mean time.
|
|
</p>
|
|
<p><b>Sample:</b></p>
|
|
<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). Note that only commands
|
|
actually needed need to be specified. The second file uses less
|
|
commands and uses defaults instead.<br>
|
|
</p>
|
|
<textarea rows="15" cols="60">$ModLoad imfile #
|
|
needs to be done just once
|
|
# File 1
|
|
$InputFileName /path/to/file1
|
|
$InputFileTag tag1:
|
|
$InputFileStateFile stat-file1
|
|
$InputFileSeverity error
|
|
$InputFileFacility local7
|
|
$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
|
|
<a href="http://www.rsyslog.com/">rsyslog</a> project.<br>
|
|
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>
|