Text File Input Module

Module Name:    imfile

Author: Rainer Gerhards <rgerhards@adiscon.com>

Description:

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.

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.

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.

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).

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.

Multiple files may be monitored by specifying $InputRunFileMonitor multiple times.

Configuration Directives:

• $InputFileName /path/to/file
  The file being monitored. So far, this must be an absolute name (no macros or templates)
• $InputFileTag tag:
  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).
• $InputFileStateFile <name-of-state-file>
  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.
• $InputFileFacility facility
  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. Default  is "local0".
• $InputFileSeverity
  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. Default is "notice".
• $InputRunFileMonitor
  This activates the current monitor. It has no parameters. If you forget this directive, no file monitoring will take place.
• $InputFilePollInterval seconds
  This is a global setting. It specifies how often files are to be polled for new data. The time specified is in seconds. The default value 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.
  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.

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

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.

Sample:

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.

[rsyslog.conf overview] [manual index] [rsyslog site]

This documentation is part of the rsyslog project.
Copyright © 2008 by Rainer Gerhards and Adiscon. Released under the GNU GPL version 3 or higher.