Log paths: routing and processing messages
This section describes how to create and configure log paths in syslog-ng Store Box(SSB). Log paths and filters allow you to select and route messages to specific destinations. You can also parse and modify the log messages in log path using message parsers and rewriter rules. The log path processes the incoming messages as follows.
-
Parse the message as a syslog message (unless message parsing is explicitly disabled for the source).
-
Classify the message using a pattern database.
-
Modify the message using rewrite rules (before filtering).
-
Filter the messages, for example, based on sender hostname or message content. If the message does not match the configured filter, syslog-ng Store Box(SSB) will not send it to the destination.
-
Parse the text of the message (that is, the ${MESSAGE} part) using a key-value parser or the sudo parser.
-
Modify the message using rewrite rules (after filtering and other parsing).
-
SSB sends the message to the destinations set in the log path. The destinations are local, optionally encrypted files on SSB, or remote servers, such as a database server.
Two log paths are available by default in the syslog-ng Store Box(SSB) appliance (see Log > Paths):
Figure 172: Log > Paths — Default logpaths of SSB
-
The first log path collects the local messages of SSB. It sends every message of the web interface, the built-in syslog-ng server, and other internal components to the local logspace.
-
The second log path collects messages sent to SSB using the default syslog sources (for details, see Default message sources in SSB) or via SNMP (for details, see Receiving SNMP messages). These messages are stored in the center logspace.
NOTE: Note that both default log paths are marked as Final: if you create a new log path that collects logs from the default sources, make sure to adjust the order of the log paths, or disable the Final option for the default log path.
This section describes how to create a new log path.
To create a new log path
-
Navigate to Log > Paths and select 
. A new log path is added to the list of log paths.
-
Select a source for the log path from the Source field. Messages arriving to this source will be processed by this log path. To add more sources to the log path, select in the source field and repeat this step.
Figure 173: Log > Paths — Creating a new logpath
Remote sources receive messages from the network, while built-in sources are messages that originate on syslog-ng Store Box(SSB). However, note that the SNMP source (for details, see Receiving SNMP messages) is listed in the built-in section.
TIP: To process every message of every source, leave the source option on all. This is equivalent to using the catchall flag of syslog-ng.
-
Select a destination for the log path from the Destination field. Messages arriving to this source will be forwarded to this destination. To add more destinations to the log path, select in the destination field and repeat this step.
NOTE: Remote destinations forward the messages to external servers or databases and are configured on the Log > Destinations page (for details, see Forwarding messages from SSB).
Local destinations store the messages locally on SSB and are configured on the Log > Logspaces page (for details, see Storing messages on SSB).
If you do not want to store the messages arriving to this log path, leave the Destination field on none.
|
|
Caution:
The none destination discards messages — messages sent only to this destination will be lost irrevocably. |
-
If you do not want other log paths to process the messages sent to a destination by this log path, select the Final option.
The order of the log paths is important, especially if you use the Final option in one or more destinations, because SSB evaluates log paths in descending order. Use the 
, 
buttons to position the log path if needed.
-
To enable flow-control for this log path, select the flow-control option. For details on how flow-control works, see Managing incoming and outgoing messages with flow-control.
NOTE: As a result of toggling the flow-control status of the logpath, the output buffer size of the logpath's destination(s) will change. For the changes to take effect, navigate to Basic Settings > System > Service control and click Restart syslog-ng.
-
If you do not want to send every message from the sources to the destinations, use filters. Select the filter to use from the Filter field, click , and configure the filter as needed. To apply more filters, click and select a new filter. Note that SSB sends only those messages to the destinations that pass every listed filter of the log path. The available filters are described in Filtering messages.
Figure 174: Log > Paths — Filtering log messages
-
Click 
. After that, the new log path will start to collect log messages.
TIP: If you do not want to activate the log path immediately, deselect the Enable option.
This section describes the filters that can be used in log paths. Every filter can be used to select (for example, priority is) or exclude (for example, priority is not) messages. The following filters are available:
-
facility: Select messages sent by a specific facility (for example, kernel).
-
host: Select messages sent by a specific host. Enter the a hostname, IP address, or a POSIX (extended) regular expression.
-
message: Select messages containing a specific keyword or POSIX (extended) regular expression in the text of the log message (excluding the headers).
-
priority: Select messages of a specific priority.
-
program: Select messages sent by a specific application. Enter the name of the application or a POSIX (extended) regular expression.
-
sender: Filter on the address of the host that sent the message to syslog-ng Store Box(SSB).
NOTE: To be able to use this filter, as a prerequisite, you must have a hostlist defined. For more information, see Creating hostlist policies.
NOTE: When using the host, message, and program filters, remember to escape special characters. The characters ()[]{}.*?+^$|\ are treated as special symbols and have to be escaped with a backslash (\) in order to be interpreted as literal characters.
NOTE: The effect of the sender and the host filters is the same if every client sends the logs directly to SSB. But if SSB receives messages from relays, then the host filter applies to the address of the clients, while the sender applies to the address of the relays.
If multiple filters are set for a log path, only messages complying to every filter are sent to the destinations. (In other words, filters are added using the logical AND operation.)
Figure 175: Log > Paths — Using custom filters
If you need more complex filtering in your log path, select the 
of the log path and enter a custom filter into the appearing field. The contents of the Custom filter field are pasted into the filter() parameter of the syslog-ng log path definition.
When defining custom filters, you can use regular expressions. By default, custom filters use POSIX-style (extended) regular expressions.
NOTE: When using POSIX regular expressions, the characters ()[]{}.*?+^$|\ are used as special symbols. Depending on how you want to use these characters and which quotation mark you use, these characters must be used differently, as summarized below:
-
When enclosing strings between double-quotes ("string"), the string is interpreted and you have to escape special characters, that is, prefix them with a backslash (\) if they are meant literally.
-
Strings between single quotes ('string') are treated as literals and are not interpreted at all, so you do not have to escape special characters.
To use other expression types, add the type() option after the regular expression. For example:
message("([0-9]+)=\\1" type("pcre"))
In this example, a PCRE regular expression with backreference is used and a match is returned if the message contains identical numbers separated by the equal sign (=). For example:
123=123
