Example Rule Specifications File

<Traverse>

<message-handler>

 <ruleset type="type_name" name="source_name">

  <rule>

   <description>descriptive_text</description>

   <pattern>regular_expression</pattern>

   <action>match_action</action>

   <mapping>

    <field name="field_name_1" match="match_index_1"/>

    <field name="field_name_2" match="match_index_2"/>

    [...]

    <field name="field_name_n" match="match_index_n"/>

   </mapping>

   <severity>severity_name</severity>

   <show-message>true</show-message>

   <auto-clear>600</auto-clear>

   <transform>new_message</transform>

   <additional-duplicate-key>${message_text}

   </additional-duplicate-key>

  </rule>

  <rule>

   [...] <!-- multiple rules -->

  </rule>

 </ruleset>

</message-handler>

</Traverse>

Rule Elements

Element Name	Description
type	file \| socket \| trap \| winevt \| syslogd
name	Matches the source name. It can be * in which case its rules are checked before any other rulesets.
description	Free-form text describing the incoming message (optional).
pattern	perl5 (hence oro) compatible regular expression. The match assumes ignorecase is set (case is ignored).
action	accept \| reject
mapping.field.name	device_name \| device_address \| a unique word
mapping.field.match	1 .. n This corresponds to one of the match items from regular_expression.
severity	ok \| warning \| critical \| unknown
show-message	true \| false If false, the remote DGE will not display the message on the console, but can still be used to trigger an action and generate reports.
auto-clear	Optional. Automatically removes the message from the console after the specified number of seconds.
transform	Converted message which is sent to the DGE.
additional-duplicate-key	The device name, device address, and event category are typically used to determine if an event is a duplicate of another. If additional fields should be considered when determining if an event is a duplicate, they must be specified here.

You can have a default rule that matches everything using the following:

<pattern>.*</pattern>

You can log each message that comes in before the rules are applied by enabling debug level logging for the message handler in the etc/log4j.conf file.

Note the following when creating rulesets:

One of device_name or device_address field is required. If one is specified, the oth er can be optional. If neither is specified, or there is no match found, then the message is dropped (because there is no way to match the message with a provisioned devices).
Within the <transform> section, the variables (${foo}) correspond to fields defined in <map> section. If a variable specified was not defined before, or was not matched, the message is dropped.
Even if the value in <transform> is specified on multiple lines for readability, the final message is on a single line. The original message is still accessible via the ${raw_message} variable. If no value is specified for this attribute, or the attribute is missing, it defaults to the message as it was originally accepted (for example, <transform>${raw_message}</transform>).
You can specify a special name * for a source type, which will be applicable to all sources of that type. The rules in this set are checked before any other rules.
If there is a ruleset with name _default, it is used after all other rules have been checked and there was no match.
If the ruleset does not extract the TIME string, then the system uses the default timestamp. However, the user can extract the TIME string (free format string), and the message handler will attempt to convert the free form text string into the proper time syntax.
As the text messages are collected by the various data sources, they are matched against all rules (sorted by the order they are read) in all files (sorted by name). At the first match (either accept or reject), no further processing is done. The message is transformed and then forwarded to the DGE.
It is important to organize the rules so that the majority of the messages are matched early on (either accepted or rejected) for better performance.

In absence of a <ruleset-defaults> entry, the following defaults are used:

Ruleset Defaults

Parameter	Default Value
match_action	accept
severity_name	ok
new_message	${raw_message)
show_message	true
auto_clear	false