[syslog-ng] Bazsi's blog: syslog-ng correllation updated

[Balazs Scheidler]

syslog-ng correllation updated

I’m trying to push syslog-ng 3.2beta1 out on the door, but as I was
writing the NEWS entry I had to realize that the latest state of the
patterndb correllation functions are undocumented so far. So here goes a
blog post which tries to summarize how it works, so that I can include
it in the NEWS entry :)

My previous post on the topic used a syntax that included explicit
“store” and “join” elements, but I’ve decided to drop those, as they
stood in the way for some more juicy functionality. What remained is
that the correllation is still focused around a “correllation state”, or
as I’ve called internally a “context”.

A context consists of a series of log messages related to each other in
some way. As new messages come in, they may be associated with a context
(e.g. added to the context). Also, when an incoming message is
identified it can trigger some actions to be performed. And these
actions can use all the information that was stored previously in the
context.

Let’s see how this work out with concrete examples: each rule in the
patterndb has a “context-id” attribute telling db-parser() which context
the given message should be associated with.

This example covers an SSH login message:


<rule id=”…” context-id=”$HOST:$PROGRAM:$PID” context-timeout=”86400″ context-scope=”global”>
  <patterns>
    <pattern>Accepted @ESTRING:usracct.authmethod: @for @ESTRING:usracct.username: @from @ESTRING:usracct.device: @port @ESTRING:: @@ANYSTRING:usracct.service@</pattern>
  </patterns>
  …
</rule>


Since multiple rules can reference the same context, multiple different
kind of messages may be added into the same context as a result. E.g.
the logout event looks like this:


<rule context-id=”$HOST:$PROGRAM:$PID” context-timeout=”0″ context-scope=”global”>
  <patterns>
    <pattern>pam_unix(sshd:session): session closed for user @ANYSTRING:usracct.username:@</pattern>
  </patterns>
  …
</rule>


As you can see a “session” is identified using the triplet ($HOST,
$PROGRAM, $PID) and these two rules correllate the login/logout events
into the same context, which means that you can create a derived event
that contains information from both of them.

Please note that it is fairly common that messages only need to be
correllated if they originate from the same host: e.g. this SSH login
message needs only to be correllated to its logout counterpart if they
both originate from the same host. In the previous example this was
achieved using explicit macros in the context-id attribute, however
since this is quite often the case, this was worked into a function of
its own right: each rule can have a context-scope attribute:


<rule id=”…” context-scope=”process” context-id=”ssh-login” context-timeout=”5″>
</rule>


The context-scope tells syslog-ng which messages need to be considered
when looking for correllations:


      * process: only consider messages that have matching $HOST,
        $PROGRAM and $PID values
      * program: only consider messages that have matching $HOST and
        $PROGRAM values
      * host: only consider messages that have matching $HOST values
      * global: any kind of message is fine


The default is to use “process”, which means that if it is true that the
same process is emitting all the messages that you want to correllate,
then you don’t need to use a variable part in your context-id attribute.
But it is also important to know that it is way faster to specify the
scope this way than it’d be to add all relevant macros to your
context-id attribute.

So far so good, we have all the functions that we used to have with the
previous versions of the functionality. But I mentioned something about
“actions” to be performed. Until now a patterndb rule basically only
identified the incoming message, possibly associated tags and name-value
pairs, but didn’t perform anything else. This is being changed: one or
more actions can be associated with a patterndb rule in order to make it
possible to react to more complex situations.

Here’s an example action:


<action rate=”1/86400″>
  <message>
    <values>
      <value name=”MESSAGE”>a patterndb rule matched</value>
    </values>
  </message>
</action>


Right now the only real response to a message is to generate another
message, but this allows us to do a couple of powerful transformations,
especially with the following options that you can specify for an action
tag:


      * condition: specifies a syslog-ng filter expression that needs to
        be matched in order to really perform the action. It is
        evaluated on the current message that matched the rule.
      * rate: <num>/<period> specifies how much messages are to be
        generated (num), in the specified time period (period). Excess
        messages are dropped. For example: “1/60″ allows 1 message /
        minute. Rates apply  to the given scope for the given
        rule/action. E.g. context-scope=”host”, rate=”1/60″ means that
        one message gets generated for _each host_ per minute.
      * trigger: specifies when to execute the action, there are two
        possible triggers right now: 
              * match: execute immediately once the rule matches
              * timeout: execute when the correllation timer expires


I’d like to highlight two things:


      * it is possible to react to the expiration of a correllation
        timer (e.g. trigger=”timeout”)
      * it is possible to generate a message only in case a given
        condition is met (e.g. “$PID” == “”)


Right now new messages are posted to the internal() driver. This is not
the way I wanted it to be, but doing my original plan would require an
enormous refactorization of the code, and it is too late for that too
happen. My original idea was to let the db-parser() emit multiple
messages, but since the current state of affairs in syslog-ng assumes
that only sources generate messages, that needs a lot of work. But hey,
we need something to do for syslog-ng 3.3, right?



-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.balabit.hu/pipermail/syslog-ng/attachments/20101011/ae43affb/attachment.htm