orchids-inputs.conf

The orchids-inputs.conf configuration file describes where Orchids will take its inputs from. It organizes input modules and dissection modules. Think of it as plumbing:

  • Use input modules to obtain data from event sources
  • Use dissection modules as pipes.

Input

Orchids can take data from several sources.  Declare a new source by writing a directive of the form INPUT module-name tag.

This states that a new instance of module module-name should be used to obtain data from source tag. What tag is depends on the module. For example:

 INPUT textfile "/var/log/messages"

instructs Orchids to open file /var/log/messages for reading, and to use the textfile module for that purpose.  As another example,

INPUT udp 514

tells Orchids to listen on port 514 for UDP packets, and to use the udp module for that purpose.

Once Orchids is running, every input module thus declared will wait for input on the given data sources, and convert it into series of Orchids events.

Orchids events are records, namely lists of pairs (field-name, field-value).  For Orchids events produced by input modules, two of these fields play a special role:

  • The next-to-last field usually replicates the tag, as a string.  This allows one to know from which text file the event was obtained (in the case of the textfile module ) for example.  However, its main purpose is to connect the Orchids event to the right dissection module.
  • The last field contains the useful content that was just read by the module: a line of text for the textfile module (of type str), an array of raw bytes for the udp module (of type bstr).

See the input modules page for more details.

Dissection

One can then connect data obtained by input modules to dissection modules by issuing directives of the form DISSECT dissection-module input-module tag.  The purpose of dissection modules is to parse data from the last fields of Orchids events.  For example:

DISSECT syslog textfile "/var/log/messages"

instructs Orchids to direct any Orchids event obtained by the textfile module with tag /var/log/messages to be fed to the syslog module for further dissection (parsing).

The input-module is in fact not restricted to be an input module, and can be a dissection module as well, allowing for cascades of dissection modules.  For example, declaring:

INPUT			        udp	514
DISSECT		bintotext	udp	514
DISSECT		syslog	  bintotext	514

states that any data obtained from a UDP connection over port 514 should be fed to the bintotext module (to convert raw packets into sequences of text lines), and that the resulting lines should be fed to the syslog module.  This is how remote events obtained through UDP, in syslog format, should be presented to Orchids.

See the dissection modules pages for more details.