Element: create-context
Description
OPTIONAL — Creates a new correlation context from the current message and its associated context. This can be used to "split" a context.
Available in syslog-ng OSE version
Attributes
-
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
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 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 Correlating log messages using pattern databases.
-
Children
-
message: A container element storing the message that is added to the new context when the action is executed.
-
inherit-mode: This attribute controls which name-value pairs and tags are propagated to the newly generated message.
-
context: syslog-ng OSE collects every name-value pair from each message stored in the context, and includes them in the generated message. If a name-value pair appears in multiple messages of the context, the value in the latest message will be used. Note that tags are not merged, the generated message will inherit the tags assigned to the last message of the context.
-
last-message: Only the name-value pairs appearing in the last message are copied. If the context contains only a single message, then it is the message that triggered the action.
-
none: An empty message is created, without inheriting any tags or name-value pairs.
For details on the message context, see Correlating log messages using pattern databases and Actions and message correlation. For details on triggering messages, see Triggering actions for identified messages
-
-
Example
The following example creates a new context whenever the rule matches. The new context receives 1000 as ID, and program as scope, and the content set in the <message> element of the <create-context> element.
<rule provider='test' id='12' class='violation'>
<patterns>
<pattern>simple-message-with-action-to-create-context</pattern>
</patterns>
<actions>
<action trigger='match'>
<create-context context-id='1000' context-timeout='60' context-scope='program'>
<message inherit-properties='context'>
<values>
<value name='MESSAGE'>context message</value>
</values>
</message>
</create-context>
</action>
</actions>
</rule>Element: tags
Description
OPTIONAL — An element containing custom keywords (tags) about the messages matching the patterns. The tags can be used to label specific events (for example user logons). It is also possible to filter on these tags later (for details, see Tagging messages). Starting with syslog-ng Open Source Edition 3.2, the list of tags assigned to a message can be referenced with the ${TAGS} macro.
Attributes
N/A
Children
-
tag: OPTIONAL — A keyword or tags applied to messages matching the rule.
Example
<tags><tag>UserLogin</tag></tags>
Correlating log messages
The syslog-ng OSE application can correlate log messages. Alternatively, you can also correlate log messages using pattern databases. For details, see Correlating log messages using pattern databases.
-
To group or correlate log messages that match a set of filters, use the grouping-by parser. This works similarly to SQL GROUP BY statements. For details, see Correlating messages using the grouping-by() parser.
-
You can correlate log messages identified using pattern databases. For details, see Correlating log messages using pattern databases.
Log messages are supposed to describe events, but applications often separate information about a single event into different log messages. For example, the Postfix e-mail server logs the sender and recipient addresses into separate log messages, or in case of an unsuccessful login attempt, the OpenSSH server sends a log message about the authentication failure, and the reason of the failure in the next message. Of course, messages that are not so directly related can be correlated as well, for example, login-logout messages, and so on.
To correlate log messages with syslog-ng OSE, you can add messages into message-groups called contexts. A context consists of a series of log messages that are related to each other in some way, for example, the log messages of an SSH session can belong to the same context. As new messages come in, they may be added to a context. Also, when an incoming message is identified it can trigger actions to be performed, for example, generate a new message that contains all the important information that was stored previously in the context.
Correlating messages using the grouping-by() parser
The syslog-ng OSE application can correlate log messages that match a set of filters. This works similarly to SQL GROUP BY statements. Alternatively, you can also correlate log messages using pattern databases. For details, see Correlating log messages using pattern databases.
Log messages are supposed to describe events, but applications often separate information about a single event into different log messages. For example, the Postfix e-mail server logs the sender and recipient addresses into separate log messages, or in case of an unsuccessful login attempt, the OpenSSH server sends a log message about the authentication failure, and the reason of the failure in the next message. Of course, messages that are not so directly related can be correlated as well, for example, login-logout messages, and so on.
To correlate log messages with syslog-ng OSE, you can add messages into message-groups called contexts. A context consists of a series of log messages that are related to each other in some way, for example, the log messages of an SSH session can belong to the same context. As new messages come in, they may be added to a context. Also, when an incoming message is identified it can trigger actions to be performed, for example, generate a new message that contains all the important information that was stored previously in the context.
How the grouping-by() parser works
+--------------------+
|Incoming log message|
+--------------------+
|
|
|
|
V
+-------------------------------------------+ No
|Does it match key(), scope(), and where()? +----------> Ignore message
+-------------------------------------------+
|
|
V
Add message to context
|
|
v No
Is it a trigger() message or --------> Wait until timeout() or a new message
has the timeout() expired?
+
|
|
v No
Does the context match having()? +-------------> Close the context
+ and do nothing
|
|
v
Inject the aggregate() log message and close the context
The grouping-by() parser has three options that determine if a message is added to a context: scope(), key(), and where().
-
The scope() option acts as an early filter, selecting messages sent by the same process (${HOST}${PROGRAM}${PID} is identical), application (${HOST}${PROGRAM} is identical), or host.
-
The key() identifies the context the message belongs to. (The value of the key must be the same for every message of the context.)
-
To use a filter to further limit the messages that are added to the context, you can use the where() option.
The timeout() option determines how long a context is stored, that is, how long syslog-ng OSE waits for related messages to arrive. If the group has a specific log message that ends the context (for example, a logout message), you can specify it using the trigger() option.
When the context is closed, and the messages match the filter set in the having() option (or the having() option is not set), syslog-ng OSE generates and sends the message set in the aggregate() option.
|
|
NOTE:
Message contexts are persistent and are not lost when syslog-ng OSE is reloaded (SIGHUP), but are lost when syslog-ng OSE is restarted. |
Declaration:
parser parser_name {
grouping-by(
key()
having()
aggregate()
timeout()
);
};For the parser to work, you must set at least the following options: key(), aggregate(), and timeout().
Note the following points about timeout values:
-
When a new message is added to a context, syslog-ng OSE will restart the timeout using the context-timeout set for the new message.
-
When calculating if the timeout has already expired or not, syslog-ng OSE uses the timestamps of the incoming messages, not system time elapsed between receiving the two messages (unless the messages do not include a timestamp, or the keep-timestamp(no) option is set). That way syslog-ng OSE can be used to process and correlate already existing log messages offline. However, the timestamps of the messages must be in chronological order (that is, a new message cannot be older than the one already processed), and if a message is newer than the current system time (that is, it seems to be coming from the future), syslog-ng OSE will replace its timestamp with the current system time.
Example: How syslog-ng OSE calculates context-timeout
Consider the following two messages:
<38>1990-01-01T14:45:25 customhostname program6[1234]: program6 testmessage <38>1990-01-01T14:46:25 customhostname program6[1234]: program6 testmessage
If the context-timeout is 10 seconds and syslog-ng OSE receives the messages within 1 sec, the timeout event will occour immediately, because the difference of the two timestamp (60 sec) is larger than the timeout value (10 sec).
-
Avoid using unnecessarily long timeout values on high-traffic systems, as storing the contexts for many messages can require considerable memory. For example, if two related messages usually arrive within seconds, it is not needed to set the timeout to several hours.
Example: Correlating Linux Audit logs
Linux audit logs tend to be broken into several log messages (generated as a list of lines). Usually, the related lines are close to each other in time, but multiple events can be logged at around the same time, which get mixed up in the output. The example below is the audit log for running ntpdate:
type=SYSCALL msg=audit(1440927434.124:40347): arch=c000003e syscall=59 success=yes exit=0 a0=7f121cef0b88 a1=7f121cef0c00 a2=7f121e690d98 a3=2 items=2 ppid=4312 pid=4347 auid=4294967295 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=(none) ses=4294967295 comm="ntpdate" exe="/usr/sbin/ntpdate" key=(null) type=EXECVE msg=audit(1440927434.124:40347): argc=3 a0="/usr/sbin/ntpdate" a1="-s" a2="ntp.ubuntu.com" type=CWD msg=audit(1440927434.124:40347): cwd="/" type=PATH msg=audit(1440927434.124:40347): item=0 name="/usr/sbin/ntpdate" inode=2006003 dev=08:01 mode=0100755 ouid=0 ogid=0 rdev=00:00 nametype=NORMAL type=PATH msg=audit(1440927434.124:40347): item=1 name="/lib64/ld-linux-x86-64.so.2" inode=5243184 dev=08:01 mode=0100755 ouid=0 ogid=0 rdev=00:00 nametype=NORMAL type=PROCTITLE msg=audit(1440927434.124:40347): proctitle=2F62696E2F7368002F7573722F7362696E2F6E7470646174652D64656269616E002D73
These lines are connected by their second field: msg=audit(1440927434.124:40347). You can parse such messages using the Linux Audit Parser of syslog-ng OSE, and then use the parsed .auditd.msg field to group the messages.
parser auditd_groupingby {
grouping-by(
key("${.auditd.msg}")
aggregate(
value("MESSAGE" "$(format-json .auditd.*)")
)
timeout(10)
);
};
For another example, see The grouping-by() parser in syslog-ng blog post