13.5.3.5. Element: rule

Location

/patterndb/ruleset/rules/rule

Description

An element containing message patterns and how a message that matches these patterns is classified.

Note

If the following characters appear in the message, they must be escaped in the rule as follows:

  • @: Use @@, for example user@@example.com

  • <: Use &lt;

  • >: Use &gt;

  • &: Use &amp;

The <rules> element may contain any number of <rule> elements.

Attributes
  • provider: The provider of the rule. This is used to distinguish between who supplied the rule, that is, if it has been created by Balabit, or added to the XML by a local user.

  • id: The globally unique ID of the rule.

  • class: The class of the rule — syslog-ng assigns this class to the messages matching a pattern of this rule.

  • context-id: OPTIONAL — An identifier to group related log messages when using the pattern database to correlate events. The ID can be a descriptive string describing the events related to the log message (for example, ssh-sessions for log messages related to SSH traffic), but can also contain macros to generate IDs dynamically. When using macros in IDs, see also the context-scope attribute. Starting with syslog-ng OSE version 3.5, if a message is added to a context, syslog-ng OSE automatically adds the identifier of the context to the .classifier.context_id macro of the message. For details on correlating messages, see Section 13.3, Correlating log messages using pattern databases.

    Note

    The syslog-ng OSE application determines the context of the message after the pattern matching is completed. This means that macros and name-value pairs created by the matching pattern database rule can be used as context-id macros.

  • context-timeout: OPTIONAL — The number of seconds the context is stored. Note that for high-traffic log servers, storing open contexts for long time can require significant amount of memory. For details on correlating messages, see Section 13.3, Correlating log messages using pattern databases.

  • context-scope: OPTIONAL — Specifies which messages belong to the same context. This attribute is used to determine the context of the message if the context-id does not specify any macros. Usually, context-scope acts a filter for the context, with context-id refining the filtering if needed. The following values are available:

    • process: Only messages that are generated by the same process of a client belong to the same context, that is, messages that have identical ${HOST}, ${PROGRAM} and ${PID} values. This is the default behavior of syslog-ng OSE if context-scope is not specified.

    • program: Messages that are generated by the same application of a client belong to the same context, that is, messages that have identical ${HOST} and ${PROGRAM} values.

    • host: Every message generated by a client belongs to the same context, only the ${HOST} value of the messages must be identical.

    • global: Every message belongs to the same context.

    Note

    Using the context-scope attribute is significantly faster than using macros in the context-id attribute.

    For details on correlating messages, see Section 13.3, Correlating log messages using pattern databases.

Children
Example
<rule provider='balabit' id='f57196aa-75fd-11dd-9bba-001e6806451b' class='violation'>

The following example specifies attributes for correlating messages as well. For details on correlating messages, see Section 13.3, Correlating log messages using pattern databases.

<rule provider='balabit' id='f57196aa-75fd-11dd-9bba-001e6806451b' class='violation' context-id='same-session' context-scope='process' context-timeout='360'>