The following describes how to configure syslog-ng Store Box(SSB) to create custom reports. Make sure that the user account has read & write/perform access to the use static subchapters privilege.
To configure SSB to create custom reports
-
Log in to the SSB web interface, and navigate to Reports > Configuration.
Figure 232: Reports > Configuration — Configuring custom reports
-
Click 
and enter a name for the custom report.
-
Reports are organized into chapters and subchapters. To add a new chapter, go to Table of contents, click Add Chapter, enter a name for the chapter, then click OK. Repeat this step to create further chapters if needed.
-
Click Add Subchapter to add various reports and statistics to the chapter. The available reports will be displayed in a pop-up window. The reports created from custom statistics are listed at the end.
-
Use the arrows to change the order of the subchapters if needed.
-
To specify how often SSB should create the report, select the relevant Generate this report every (Day, Week, Month) option. Weekly reports are created on Mondays, while monthly reports on the first day of the month. You can select multiple options simultaneously.
If you want to generate the report only manually, leave this field empty.
-
By default, members of the search group can access the custom reports via the SSB web interface. To change this, enter the name of a different group into the Reports are accessible by the following groups field, or click to grant access to other groups.
NOTE: Members of the listed groups will be able to access only these custom reports even if their groups do not have read access to the Reporting > Reports page. However, only those reports will be listed, to which their group has access.
-
By default, SSB sends out the reports in email to the address set in the Basic Settings > Management > Mail settings > Send reports to field.
NOTE: If this address is not set, the report is sent to the SSB administrator's email address.
-
To disable email sending, unselect the Send reports in e-mail option.
-
To email the reports to a different address, select Recipient > Custom address, and enter the email address where the reports should be sent. Click to list multiple email addresses if needed.
-
Click 
.
Classifying messages with pattern databases
Using the pattern database allows you to classify messages into various categories, receive alerts on certain messages, and to collect unknown messages using artificial ignorance.
Figure 233: Log > Pattern Database — Pattern database
Note that the classification of messages is always performed, but its results are used only if you specifically enable the relevant options on the Log > Options page.
Figure 234: Log > Options — Enabling artificial ignorance and pattern-matching alerts
-
To receive alerts on messages classified as Violation, navigate to Log > Options and enable the Alerts option.
-
To receive reports on messages not included in the pattern database, navigate to Log > Options and enable the Artificial ignorance option.
The pattern database is organized as follows:
Figure 235: The structure of the pattern database
-
The pattern database consists of rulesets. A ruleset consists of a Program Pattern and a set of rules: the rules of a ruleset are applied to log messages if the name of the application that sent the message matches the Program Pattern of the ruleset. The name of the application (the content of the ${PROGRAM} macro) is compared to the Program Patterns of the available rulesets, and then the rules of the matching rulesets are applied to the message.
-
The Program Pattern can be a string that specifies the name of the appliation or the beginning of its name (for example, to match for sendmail, the program pattern can be sendmail, or just send), and the Program Pattern can contain pattern parsers. Note that pattern parsers are completely independent from the syslog-ng parsers used to segment messages. Additionally, every rule has a unique identifier: if a message matches a rule, the identifier of the rule is stored together with the message.
-
Rules consist of a message pattern and a class. The Message Pattern is similar to the Program Pattern, but is applied to the message part of the log message (the content of the ${MESSAGE} macro). If a message pattern matches the message, the class of the rule is assigned to the message (for example, Security, Violation, and so on).
-
Rules can also contain additional information about the matching messages, such as the description of the rule, an URL, name-value pairs, or free-form tags. This information is displayed by the syslog-ng Store Box(SSB) appliance in the e-mail alerts (if alerts are requested for the rule), and are also displayed on the search interface.
-
Patterns can consist of literals (keywords, or rather, keycharacters) and pattern parsers.
NOTE: If the ${PROGRAM} part of a message is empty, rules with an empty Program Pattern are used to classify the message.
If the same Program Pattern is used in multiple rulesets, the rules of these rulesets are merged, and every rule is used to classify the message. Note that message patterns must be unique within the merged rulesets, but the currently only one ruleset is checked for uniqueness.
This section describes how patterns work. This information applies to program patterns and message patterns alike, even though message patterns are used to illustrate the procedure.
Figure 236: Applying patterns
Patterns can consist of literals (keywords, or rather, keycharacters) and pattern parsers. Pattern parsers attempt to parse a sequence of characters according to certain rules.
NOTE: Wildcards and regular expressions cannot be used in patterns. The @ character must be escaped, that is, to match for this character, you have to write @@ in your pattern. This is required because pattern parsers of syslog-ng are enclosed between @ characters.
When a new message arrives, syslog-ng attempts to classify it using the pattern database. The available patterns are organized alphabetically into a tree, and syslog-ng inspects the message character-by-character, starting from the beginning. This approach ensures that only a small subset of the rules must be evaluated at any given step, resulting in high processing speed. Note that the speed of classifying messages is practically independent from the total number of rules.
For example, if the message begins with the Apple string, only patterns beginning with the character A are considered. In the next step, syslog-ng selects the patterns that start with Ap, and so on, until there is no more specific pattern left.
Note that literal matches take precedence over pattern parser matches: if at a step there is a pattern that matches the next character with a literal, and another pattern that would match it with a parser, the pattern with the literal match is selected. Using the previous example, if at the third step there is the literal pattern Apport and a pattern parser Ap@STRING@, the Apport pattern is matched. If the literal does not match the incoming string (foe example, Apple), syslog-ng attempts to match the pattern with the parser. However, if there are two or more parsers on the same level, only the first one will be applied, even if it does not perfectly match the message.
If there are two parsers at the same level (for example, Ap@STRING@ and Ap@QSTRING@), it is random which pattern is applied (technically, the one that is loaded first). However, if the selected parser cannot parse at least one character of the message, the other parser is used. But having two different parsers at the same level is extremely rare, so the impact of this limitation is much less than it appears.
