Input modules

The purpose of input modules is to read data from a source and cut into into Orchids events, namely certain records of field/value pairs.

A typical example is the textfile module, which reads data from a file, a pipe, or a Unix socket, and returns one event per text line; or the udp module, which reads raw packets of data from a UDP connection; or the bintotext module, which takes an Orchids event and converts its last field, which is a raw binary string, into sequences of text lines.

The fields declared by an input module must be at least two, and the last two play a special role:

  • The last field is the one that dissection modules may dissect.  For example, the last field provided by textfile is called .textfile.line, and contains the last line read from the given file.
  • The next-to-last field is the dissection key, or tag.  It is used by Orchids to decide what dissection module (if any) should be used to parse the last field.  For example, the next-to-last field provided by textfile is called .textfile.file; it contains the name of the file, pipe, or Unix socket from which the event was obtained, and depending on it, Orchids can be configured to parse lines coming from that source using the syslog or the generic module, say.

Every input module also provides an INPUT configuration directive, so that one could in principle write, inside nn_mod_textfile.conf, one or several lines of the form `INPUT file’.  That is frowned upon.  Instead, you should write INPUT directives in the orchids-inputs.conf file. They have the slightly different syntax `INPUT module-name file’ there, and this is completely synonymous with writing `INPUT file’ between `<module module-name>' and `</module>'.  The point is that the whole plumbing should be described in the single file orchids-inputs.conf.