generic module is a dissection module: its purpose is to take an Orchids event, parse one of its text fields and return a refined Orchids events, with additional fields. Typically, the
generic module is meant to dissect text coming from the
generic module is however very special. In a sense, it is a meta-module, one that allows you to define new, so-called virtual modules, whose parsing methods are defined by regular expressions.
We explain how that works on an example. The
syslog module may have to dissect messages such as:
Jan 27 11:32:06 laramie dhclient: DHCPREQUEST on eth0 to 192.168.30.1 port 67
In that case, it will produce a last field
.syslog.msg equal to the block of text
"DHCPREQUEST on eth0 to 192.168.30.1 port 67". We would like to dissect that further.
generic module allows you to do that, based on regular expressions.
First, one should plug the
generic module so that it dissects that kind of message. The
generic module defines a so-called virtual module called
dhclient and which does just that. We shall describe it below. The plugging is done by the following line in
$OCONF/orchids-inputs.conf, instructing Orchids to let the
dhclient virtual module parse the last field,
.syslog.msg (in the example,
"DHCPREQUEST on eth0 to 192.168.30.1 port 67"), provided by the
syslog module, on the condition that its next-to-last field,
.syslog.prog, is equal to
"dhclient" (which is the case in our example).
DISSECT dhclient syslog "dhclient"
contains a list of declarations of virtual modules. Virtual modules work exactly like actual modules, except you do not need to load any shared library at start-up time to start them. Instead, virtual modules work by parsing sets of regular expressions.
We describe the standard
dhclient virtual module, which is part of the standard configuration file for the
That module is meant to parse the
syslog messages produced by the
dhclient program. That means that you should see
This declares a new virtual module with name
dhclient. Every virtual module consists of a list of
</fieldmatch> declarations. Here are some of them, and we start with the first one. The order is important: the first matching regular expression is the one that is considered to parse the given block of text.
<fieldmatch "^(bound) to ([0-9.]+) -- renewal in ([0-9]+) seconds\\."> str_field action 1 Action ipv4_field ip 2 Ip address int_field renewal 3 Renewal time </fieldmatch>
Here the regular expression matches any message starting with
"bound to " followed by an IP address, followed by
" -- renewal in " , followed by a number, followed by
" seconds." (and possibly other text: if we wanted to match that exactly, we woud add “
$" at the end of the regular expression, to match the end of text).
The parenthesized subexpressions,
([0-9]+) are recognized as subexpressions 1, 2, and 3 respectively, and converted to types
int, respectively. The possible field declarations are of the form:
_field⟨field name⟩ ⟨field number⟩ ⟨description⟩
The ⟨field name⟩ is any valid Orchids identifier, the ⟨field number⟩ is any non-negative integer, and the ⟨description⟩ consists of the whole remainder of the line. The allowed ⟨
type⟩s are the basic types
. For each, the
generic module will automatically do the required conversion. Hence, the above
> declaration will declare the following Orchids fields:
(No, there is no way to specify any monotony in virtual modules yet, sorry.)
You will have noticed that this first regular expression does not match the block of text of our example,
"DHCPREQUEST on eth0 to 192.168.30.1 port 67". That is matched by the 5th
> declaration (among 6) in the virtual module:
<fieldmatch "^(DHCPREQUEST) on ([^ ]+) to ([0-9.]+) port ([0-9]+)$"> str_field method 1 str_field interface 2 ipv4_field dst_ip 3 Destination IP address int_field port 4 </fieldmatch>
That declaration declares the following fields:
||Destination IP address|
so that, on our example, we will obtain:
192.168.30.1(as an ipv4 address)
After all those
> declarations, we end with:
to end the declaration of the virtual module. That finishes the declaration of our example virtual module
dhclient. There are many others in
$OCONF/conf.d/12_mod_generic.conf, and the previous section for examples. The virtual modules are all declared dissectable, in case one would want to further dissect one of the fields they produce.
In previous versions of Orchids, one could see all declarations of virtual modules enclosed in
</hook> declarations, for example:
<hook syslog "dhclient">
hook command said that any event produced by the
syslog module whose next-to-last field
.syslog.prog field is equal to
"dhclient" (as in our example) should be parsed by the following virtual module.
This still works, for the time being, but contradicts the principle that all the plumbing of sources and dissectors should be described in the sole file