20.4. Filtering Log Messages

Home Prev	cOS Stream 4.00.03 Administration Guide	Next

It is possible to specify filters which decide which messages are sent to a log receiver. This can be done in either or both the following ways:

By specifying the LogSeverity property of a log receiver object. This means that only messages of the severities specified will be generated.
By associating one or more LogReceiverMessageException objects with a log receiver object. Each LogReceiverMessageException object can specify a set of filtering criteria which can include the category, ID or severity of messages and specify if the filtered messages are to be sent or not sent.

Multiple LogReceiverMessageException objects associated with a log receiver will be processed sequentially looking for a match. This processing will stop as soon as one exception triggers.

These methods are described next.

Filtering on Log Severity

The optional LogSeverity property of a log receiver object can be used to specify what severities are sent to the receiver. By default, all log messages except those with the Debug severity are sent. However, an administrator may only want certain severities sent. For example, it might be desirable to send only Emergency and Alert messages and no other severities.

This is achieved by setting the LogSeverity property to a list of the severities to be sent. For example, if only the Alert severity is specified then only that severity will be sent.

Example 20.2. Configuring the Log Severity Property

In this example, it is assumed that a Syslog server has already been configured in cOS Stream with the logical name my_syslog. The aim is to have only the log messages with a severity of Emergency or Alert sent to this server.

Command-Line Interface

System:/> set LogReceiver LogReceiverSyslog my_syslog
			LogSeverity=Emergency,Alert

Log Receiver Message Exceptions

After the LogSeverity property is applied, any associated LogReceiverMessageException filters are applied. These exceptions can explicitly include or exclude log messages of certain types for sending to the log server.

LogReceiverMessageException objects are created as one or more children to the log receiver object. Each child object acts as a filter for its parent and can have a combination of the following properties:

LogCategory

This property is optional and specifies the category, or categories, of log messages that will be filtered out by the exception. For example, the following would filter out all messages that have a log category of ARP :
```
			LogCategory=ARP
```
A log event message can belong to more than one category. A match is found when any of the log message's categories matches the specified category.

It is possible to specify a list of categories for the filter. If this is done then the message must belong to all the specified categories to be caught. For example, the following would filter out messages that belong to both the ARP category and the VALIDATE category :
```
			LogCategory=ARP,VALIDATE
```
It is possible to specify that something should not be in a category by preceding the category name with a minus "-" sign. For example, the following would specify all log messages not in the ARP category :
```
			LogCategory=-ARP
```
Categories that must be present can be combined with categories that should not. For example, the following specifies that filtered messages must belong to the category ARP but should not belong to the category VALIDATE :
```
			LogCategory=ARP,-VALIDATE
```

LogID

This specifies a specific log message ID to which the filter applies. The ID of specific log messages can be found in the separate Clavister NetShield Firewall Log Reference Guide. The LogID property is treated as a string value and any leading zeros can be omitted. For example, to filter for the log message with the ID of 269 :
```
			LogID=269
```
Since this identifies a unique message, neither LogCategory or LogSeverity properties should be specified along with the ID.

If the LogID is not specified then it defaults to "*" which is all IDs. This can also be explicitly stated as :
```
			LogID=*
```

Action

This is a mandatory property and can be one of the following:
1. EXCLUDE (the default)
  
  This will exclude the filtered log messages from being sent to the receiver.
2. INCLUDE
  
  This will include the filtered log messages for sending to the log receiver.

LogSeverity

This is an optional property to specify that the severity level will be filtered. To filter all messages with a severity of Emergency :
```
			LogSeverity=Emergency
```
Multiple severities can be specified. To filter out all messages with either a severity of Emergency or Alert :
```
			LogSeverity=Emergency,Alert
```
As discussed before, filtering is for only the severities specified. There is no automatic inclusion of lesser or greater severities.

	Note: The log event message severity cannot be changed
	Each log event message has a single severity already assigned to it. This severity is fixed and cannot be changed. Each message's severity is documented in the separate Clavister NetShield Firewall Log Reference Guide.

Example 20.3. Adding a Log Message Exception

In this example, it is assumed that a Syslog server has already been configured in cOS Stream with the logical configuration name my_syslog. The requirement is to exclude the log message 161 ("Failed to Rekey IKE SA").

Command-Line Interface

First, change the current context to be the log receiver object:

System:/> cc LogReceiver LogReceiverSyslog my_syslog

Now, add the message exception:

System:/LogReceiverSyslog/my_syslog> add LogReceiverMessageException
			LogID=161
			Action=EXCLUDE

All the message exceptions can be listed for this receiver:

System:/LogReceiverSyslog/my_syslog> show

LogReceiverMessageException

  # Category Log Message ID Action
  - -------- -------------- -------
+ 1 IKE      161            EXCLUDE

Note that the object gets a unique index number to identify it, in this case 1, and this is used to refer to the exception in the CLI.

Finally, change back to the default CLI context:

System:/LogReceiverSyslog/my_syslog> cc
System:/>