1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
3
<meta http-equiv="Content-Language" content="en"><title>Text File Input Monitor</title></head>
5
<h1>Text File Input Module</h1>
6
<p><b>Module Name: imfile</b></p>
7
<p><b>Author: </b>Rainer Gerhards
8
<rgerhards@adiscon.com></p>
9
<p><b>Description</b>:</p>
10
<p>Provides the ability to convert any standard text file into
11
a syslog message. A standard
12
text file is a file consisting of printable characters with lines
13
being delimited by LF.</p>
14
<p>The file is read line-by-line and any line read is passed to
15
rsyslog's rule engine. The rule engine applies filter conditons and
16
selects which actions needs to be carried out.</p>
17
<p>As new lines are written they are taken from the file and
18
processed. Please note that this happens based on a polling interval
19
and not immediately. The file monitor support file rotation. To fully
20
work, rsyslogd must run while the file is rotated. Then, any remaining
21
lines from the old file are read and processed and when done with that,
22
the new file is being processed from the beginning. If rsyslogd is
23
stopped during rotation, the new file is read, but any not-yet-reported
24
lines from the previous file can no longer be obtained.</p>
25
<p>When rsyslogd is stopped while monitoring a text file, it
26
records the last processed location and continues to work from there
27
upon restart. So no data is lost during a restart (except, as noted
28
above, if the file is rotated just in this very moment).</p>
29
<p>Currently, the file must have a fixed name and location
30
(directory). It is planned to add support for dynamically generating
31
file names in the future.</p>
32
<p>Multiple files may be monitored by specifying
33
$InputRunFileMonitor multiple times.
35
<p><b>Configuration Directives</b>:</p>
37
<li><strong>$InputFileName /path/to/file</strong><br>
38
The file being monitored. So far, this must be an absolute name (no
39
macros or templates)</li>
40
<li><span style="font-weight: bold;">$InputFileTag
42
The tag to be used for messages that originate from this file. If you
43
would like to see the colon after the tag, you need to specify it here
44
(as shown above).</li>
45
<li><span style="font-weight: bold;">$InputFileStateFile
46
<name-of-state-file></span><br>
47
Rsyslog must keep track of which parts of the to be monitored file it
48
already processed. This is done in the state file. This file always is
49
created in the rsyslog working directory (configurable via
50
$WorkDirectory). Be careful to use unique names for different files
51
being monitored. If there are duplicates, all sorts of "interesting"
52
things may happen. Rsyslog currently does not check if a name is
53
specified multiple times.</li>
54
<li><span style="font-weight: bold;">$InputFileFacility
56
The syslog facility to be assigned to lines read. Can be specified in
57
textual form (e.g. "local0", "local1", ...) or as numbers (e.g. 128 for
58
"local0"). Textual form is suggested. <span style="font-weight: bold;">Default</span> is
59
"local0".<span style="font-weight: bold;"></span></li>
60
<li><span style="font-weight: bold;">$InputFileSeverity</span><br>
62
syslog severity to be assigned to lines read. Can be specified in
63
textual form (e.g. "info", "warning", ...) or as numbers (e.g. 4 for
64
"info"). Textual form is suggested. <span style="font-weight: bold;">Default</span>
66
<li><span style="font-weight: bold;">$InputRunFileMonitor</span><br>
67
This <span style="font-weight: bold;">activates</span>
68
the current monitor. It has no parameters. If you forget this
69
directive, no file monitoring will take place.</li>
70
<li><span style="font-weight: bold;">$InputFilePollInterval
72
This is a global setting. It specifies how often files are to be polled
73
for new data. The time specified is in seconds. The <span style="font-weight: bold;">default value</span> is 10
74
seconds. Please note that future
75
releases of imfile may support per-file polling intervals, but
76
currently this is not the case. If multiple $InputFilePollInterval
77
statements are present in rsyslog.conf, only the last one is used.<br>
78
A short poll interval provides more rapid message forwarding, but
79
requires more system ressources. While it is possible, we stongly
80
recommend not to set the polling interval to 0 seconds. That will make
81
rsyslogd become a CPU hog, taking up considerable ressources. It is
82
supported, however, for the few very unusual situations where this
83
level may be needed. Even if you need quick response, 1 seconds should
84
be well enough. Please note that imfile keeps reading files as long as
85
there is any data in them. So a "polling sleep" will only happen when
86
nothing is left to be processed.</li>
88
<b>Caveats/Known Bugs:</b>
89
<p>So far, only 100 files can be monitored. If more are needed,
90
the source needs to be patched. See define MAX_INPUT_FILES in imfile.c</p><p>Powertop
91
users may want to notice that imfile utilizes polling. Thus, it is no
92
good citizen when it comes to conserving system power consumption. We
93
are currently evaluating to move to inotify(). However, there are a
94
number of subtle issues, which needs to be worked out first. We will
95
make the change as soon as we can. If you can afford it, we recommend
96
using a long polling interval in the mean time.
99
<p>The following sample monitors two files. If you need just one,
100
remove the second one. If you need more, add them according to the
101
sample ;). This code must be placed in /etc/rsyslog.conf (or wherever
102
your distro puts rsyslog's config files). Note that only commands
103
actually needed need to be specified. The second file uses less
104
commands and uses defaults instead.<br>
106
<textarea rows="15" cols="60">$ModLoad imfile.so #
107
needs to be done just once
109
$InputFileName /path/to/file1
111
$InputFileStateFile stat-file1
112
$InputFileSeverity error
113
$InputFileFacility local7
116
$InputFileName /path/to/file2
118
$InputFileStateFile stat-file2
122
# check for new lines every 10 seconds
123
$InputFilePollingInterval 10
125
<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>]
126
[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
127
<p><font size="2">This documentation is part of the
128
<a href="http://www.rsyslog.com/">rsyslog</a>
130
Copyright � 2008 by <a href="http://www.gerhards.net/rainer">Rainer
132
<a href="http://www.adiscon.com/">Adiscon</a>.
133
Released under the GNU GPL version 3 or higher.</font></p>
b'\\ No newline at end of file'
added
removed
doc/imfile.html
