Pattern parsers attempt to parse a part of the message using rules specific to the type of the parser. Parsers are enclosed between @ characters. The syntax of parsers is the following:
-
a beginning @ character,
-
the type of the parser written in capitals,
-
optionally a name,
-
parameters of the parser, if any, and
-
a closing @ character.
Example: Pattern parser syntax
A simple parser:
@STRING@
A named parser:
@STRING:myparser_name@
A named parser with a parameter:
@STRING:myparser_name:*@
A parser with a parameter, but without a name:
@STRING::*@
Patterns and literals can be mixed together. For example, to parse a message that begins with the Host: string followed by an IP address (for example, Host: 192.168.1.1), the following pattern can be used: Host:@IPv4@.
NOTE: Note that using parsers is a CPU-intensive operation. Use the ESTRING and QSTRING parsers whenever possible, as these can be processed much faster than the other parsers.
Example: Using the STRING and ESTRING parsers
For example, look at the following message: user=joe96 group=somegroup.
-
@STRING:mytext:@ parses only to the first non-alphanumeric character (=), parsing only user, so the value of the ${mytext} macro will be user
-
@STRING:mytext:=@ parses the equation mark as well, and proceeds to the next non-alphanumeric character (the whitespace), resulting in user=joe96
-
@STRING:mytext:= @ will parse the whitespace as well, and proceed to the next non-alphanumeric non-equation mark non-whitespace character, resulting in user=joe96 group=somegroup
Of course, usually it is better to parse the different values separately, like this: "user=@STRING:user@ group=@STRING:group@".
If the username or the group may contain non-alphanumeric characters, you can either include these in the second parameter of the parser (as shown at the beginning of this example), or use an ESTRING parser to parse the message till the next whitespace: "user=@ESTRING:user: @group=@ESTRING:group: @".
The following parsers are available in syslog-ng PE.
@ANYSTRING@
Parses everything to the end of the message, you can use it to collect everything that is not parsed specifically to a single macro. In that sense its behavior is similar to the greedy() option of the CSV parser.
@DOUBLE@
An obsolete alias of the @FLOAT@ parser.
@ESTRING@
This parser has a required parameter that acts as the stopcharacter: the parser parses everything until it finds the stopcharacter. For example, to stop by the next " (double quote) character, use @ESTRING::"@. You can use the colon (:) as stopcharacter as well, for example: @ESTRING:::@. You can also specify a stopstring instead of a single character, for example, @ESTRING::stop_here.@. The @ character cannot be a stopcharacter, nor can line-breaks or tabs.
@FLOAT@
A floating-point number that may contain a dot (.) character. (Up to syslog-ng 3.1, the name of this parser was @DOUBLE@.)
@IPv4@
Parses an IPv4 IP address (numbers separated with a maximum of 3 dots).
@IPv6@
Parses any valid IPv6 IP address.
@IPvANY@
Parses any IP address.
@NLSTRING@
This parser parses everything until the next new-line character (more precisely, until the next Unix-style LF or Windows-style CRLF character). For single-line messages, NLSTRING is equivalent with ANYSTRING. For multi-line messages, NLSTRING parses to the end of the current line, while ANYSTRING parses to the end of the message. Using NLSTRING is useful when parsing multi-line messages, for example, Windows logs. For example, the following pattern parses information from Windows security auditing logs.
<pattern>Example-PC\Example: Security Microsoft Windows security auditing.: [Success Audit] A new process has been created.
Subject:
Security ID: @LNSTRING:.winaudit.SubjectUserSid@
Account Name: @LNSTRING:.winaudit.SubjectUserName@
Account Domain: @LNSTRING:.winaudit.SubjectDomainName@
Logon ID: @LNSTRING:.winaudit.SubjectLogonId@
Process Information:
New Process ID: @LNSTRING:.winaudit.NewProcessId@
New Process Name: @LNSTRING:.winaudit.NewProcessName@
Token Elevation Type: @LNSTRING:.winaudit.TokenElevationType@
Creator Process ID: @LNSTRING:.winaudit.ProcessId@
Process Command Line: @LNSTRING:.winaudit.CommandLine@
Token Elevation Type indicates the type of token that was assigned to the new process in accordance with User Account Control policy.</pattern>
@NUMBER@
A sequence of decimal (0-9) numbers (for example, 1, 0687, and so on). Note that if the number starts with the 0x characters, it is parsed as a hexadecimal number, but only if at least one valid character follows 0x. A leading hyphen (–) is accepted for non-hexadecimal numbers, but other separator characters (for example, dot or comma) are not. To parse floating-point numbers, use the @FLOAT@ parser.
@QSTRING@
Parse a string between the quote characters specified as parameter. Note that the quote character can be different at the beginning and the end of the quote, for example: @QSTRING::"@ parses everything between two quotation marks ("), while @QSTRING:<>@ parses from an opening bracket to the closing bracket. The @ character cannot be a quote character, nor can line-breaks or tabs.
@STRING@
A sequence of alphanumeric characters (0-9, A-z), not including any whitespace. Optionally, other accepted characters can be listed as parameters (for example, to parse a complete sentence, add the whitespace as parameter, like: @STRING:: @). Note that the @ character cannot be a parameter, nor can line-breaks or tabs.
The V5 database format has the following differences compared to the V4 format:
-
The <ruleset> element can now store multiple reference URLs using the new <rule_urls> element. For details, see Element: ruleset.
-
In an <action>, you can now initialize a new context. As a result, the <message> element is not required. For details, see Element: create-context.
-
The inherit-properties attribute is deprecated, use the inherit-mode attribute instead. For details, see Element: action.
Pattern databases are XML files that contain rules describing the message patterns. For sample pattern databases, see Downloading sample pattern databases.
The following scheme describes the V5 format of the pattern database. This format is backwards-compatible with the earlier formats.
For a sample database containing only a single pattern, see Example: A pattern database containing a single rule.
TIP: Use the pdbtool utility that is bundled with syslog-ng to test message patterns and convert existing databases to the latest format. For details, see The pdbtool manual page.
To automatically create an initial pattern database from an existing log file, use the pdbtool patternize command. For details, see The pdbtool manual page.
Example: A pattern database containing a single rule
The following pattern database contains a single rule that matches a log message of the ssh application. A sample log message looks like:
Accepted password for sampleuser from 10.50.0.247 port 42156 ssh2
The following is a simple pattern database containing a matching rule.
<patterndb version='5' pub_date='2010-10-17'>
<ruleset name='ssh' id='123456678'>
<pattern>ssh</pattern>
<rules>
<rule provider='me' id='182437592347598' class='system'>
<patterns>
<pattern>Accepted @QSTRING:SSH.AUTH_METHOD: @ for@QSTRING:SSH_USERNAME: @from\ @QSTRING:SSH_CLIENT_ADDRESS: @port @NUMBER:SSH_PORT_NUMBER:@ ssh2</pattern>
</patterns>
</rule>
</rules>
</ruleset>
</patterndb>
Note that the rule uses macros that refer to parts of the message, for example, you can use the ${SSH_USERNAME} macro refer to the username used in the connection.
The following is the same example, but with a test message and test values for the parsers.
<patterndb version='4' pub_date='2010-10-17'>
<ruleset name='ssh' id='123456678'>
<pattern>ssh</pattern>
<rules>
<rule provider='me' id='182437592347598' class='system'>
<patterns>
<pattern>Accepted @QSTRING:SSH.AUTH_METHOD: @ for@QSTRING:SSH_USERNAME: @from\ @QSTRING:SSH_CLIENT_ADDRESS: @port @NUMBER:SSH_PORT_NUMBER:@ ssh2</pattern>
</patterns>
<examples>
<example>
<test_message>Accepted password for sampleuser from 10.50.0.247 port 42156 ssh2</test_message>
<test_values>
<test_value name="SSH.AUTH_METHOD">password</test_value>
<test_value name="SSH_USERNAME">sampleuser</test_value>
<test_value name="SSH_CLIENT_ADDRESS">10.50.0.247</test_value>
<test_value name="SSH_PORT_NUMBER">42156</test_value>
</test_values>
</example>
</examples>
</rule>
</rules>
</ruleset>
</patterndb>
