Modifying Log Messages

Problem

You wish to change the default attributes of particular system-generated log messages.

Solution

In order to modify system log messages, you must configure the Embedded Syslog Manager (ESM) by using a combination of configuration commands and TCL scripts. First you must write a TCL script to perform a certain task and make it available via TFTP. In this simple example, the TCL script in Example 18-3 filters out a particular system log message (clear counters) and permits all other messages to be forwarded as normal.

Example 18-3. delcounters.tcl

# delcounters.tcl This script deletes all log messages that
# have the mnemonic "COUNTERS". 
if { [string compare -nocase COUNTERS $::mnemonic ] == 0 } {
return ""
} else {
return $::orig_msg
}

Now we must configure the router to retrieve the TCL script we've just created and implement it:

Router2#configure terminal 
Enter configuration commands, one per line. End with CNTL/Z.
Router2(config)#logging filter tftp://172.25.1.1/delcounters.tcl
Router2(config)#logging host 172.25.1.1 filtered
Router2(config)#end
Router2#

Discussion

The ESM was introduced in IOS Version 12.3(2)T, and it provides a programmable interface that allows you to filter, escalate, correlate, route, and customize system logging messages. The ESM allows you full control of system log messages via Tool Command Language-based (TCL) scripts, which can be stored locally or remotely.

In our example, we configured the router to delete all "clear counters" log messages while leaving all other system log messages to pass untouched. This is the most simple and practical example of the ESM in use. If we wanted to delete multiple system message types, we could modify the TCL script or load multiple TCL scripts into the router:

Router2#configure terminal 
Enter configuration commands, one per line. End with CNTL/Z.
Router2(config)#logging filter tftp://172.25.1.1/delcounters.tcl
Router2(config)#logging filter flash:test.tcl
Router2(config)#logging host 172.25.1.1 filtered
Router2(config)#end
Router2#

TCL filter scripts can be loaded by a wide variety of methods, both locally and remotely. For instance, scripts can be loaded remotely via TFTP, SCP, FTP, HTTP, etc., and TCL scripts can be locally stored in system flash or nvram. We recommend loading scripts locally whenever possible; however, it sometimes makes sense to keep scripts stored remotely. For instance, if a large number of routers utilize the same script, then keeping it centrally located makes administration and modification easier.

To view the ESM configuration on a router, use the show logging command:

Router2#show logging 
Syslog logging: enabled (1 messages dropped, 1 messages rate-limited,
 0 flushes, 0 overruns, xml enabled, filtering enabled)
 Console logging: level debugging, 166 messages logged, xml enabled,
 filtering disabled
 Monitor logging: level debugging, 64 messages logged, xml disabled,
 filtering enabled
 Buffer logging: level debugging, 119 messages logged, xml disabled,
 filtering disabled
 Logging Exception size (4096 bytes)
 Count and timestamp logging messages: enabled

Filter modules:
 tftp://172.25.1.1/delcounters.tcl 
 flash:test.tcl 

 Trap logging: level informational, 129 message lines logged
 Logging to 172.25.1.1 (udp port 514, audit disabled, link up), 107 message lines logged, xml disabled,
 filtering enabled
 Logging to 172.25.1.3 (udp port 514, audit disabled, link up), 129 message lines logged, xml disabled,
 filtering disabled
 
Router2#

Notice that a new section has been added to the output of the show logging command called "Filter modules". Below this heading is a list of currently configured TCL filters. Please be aware that the order in which the filters are configured can affect the results of the filters. Also notice that filtering has been enabled on remote host 172.25.1.1, as we configured it earlier. ESM log filtering can be enabled on all logging facilities by using the keyword filtered:

Router2#configure terminal 
Enter configuration commands, one per line. End with CNTL/Z.
Router2(config)#logging buffered filtered
Router2(config)#logging monitor filtered 
Router2(config)#logging console filtered
Router2(config)#logging host 172.25.1.1 filtered
Router2(config)#end
Router2#

In our first eample we demonstrated how to filter out a specific system log message "clear counters." In the next example, we will filter out an entire group of messages. Before we proceed, let's take a look at sample log messge and examine its standard format. The following is a sample line protocol log message:

%LINEPROTO-5-UPDOWN: Line protocol on Interface Serial0, changed state to up

All system log messages take the basic standard format of the following:

%--:

In this example, then, the facility would be "LINEPROTO", severity would be "5", the mnemonic would be "UPDOWN", and the message-text would be "Line protocol on Interface Serial0, changed state to up."

Looking back at our first TCL script, you'll see that we filtered on the mnemonic and deleted all log messages that had the mnemonic of "COUNTERS". The script in Example 18-4 filters out all log messages with the facility equal to "LINEPROTO".

Example 18-4. facilitydel.tcl

# facilitydel.tcl This script deletes all log messages that begin
# with the facility named "LINEPROTO".
if { [string compare -nocase LINEPROTO $::facility ] == 0 } {
return ""
} else {
return $::orig_msg
}

So far, we've looked at two pretty simple TCL scripts. Now let's look at a more sophisticated TCL script that Cisco has created to change the severity level of a given system log message. It's particularly interesting because the script also accepts command-line arguments, which the router must pass to it.

As we mentioned earlier, ESM filters can perform a number of tasks, including the modification of system hardcoded severity levels. Example 18-5 modifies whatever log message you specify to the new severity level you provide.

Example 18-5. sevrtyincr.tcl

# sevrityincr.tcl Increases the severity level of a syslog message.
# Requires two arguments, first the mnemonic and 
# second the new severity level. 
# E.g., STATECHANGE 3
if { [string length $::orig_msg] == 0} {
 return ""
}

if { [info exists ::cli_args] } {
 set args [split $::cli_args]
 if { [ string compare -nocase [lindex $args 0] $::mnemonic ] == 0 } {
 set ::severity [lindex $args 1]
 set sev_index [ string first [lindex $args 0] $::orig_msg ] 
 if { $sev_index >= 2 } {
 incr sev_index -2
 return [string replace $::orig_msg $sev_index $sev_index [lindex $args 1]]
 }
 }
}

return $::orig_msg

Before we implement this ESM script, let's apply it to a real world situation. One particularly important system log message that we feel has been assigned a low severity level is the HSRP change of state log message. By default, the HSRP change of state log message is assigned a rather low severity level of 6 (informational). For this example, we're going to assign it a new severity level of 3 (Errors):

Router2#configure terminal 
Enter configuration commands, one per line. End with CNTL/Z.
Router2(config)#logging filter tftp://172.25.1.1/sevrtyincr.tcl args STATECHANGE 3
Router2(config)#logging host 172.25.1.1 filtered 
Router2(config)#end
Router2#

Notice that in this example we passed two arguments to the TCL script, "STATECHANGE" and "3". The first argument indicates the mnemonic of the log message we wish to modify, and the second argument indicates the new severity level. The nice thing about writing your TCL script to accept arguments is that you can use the same script to modify multiple system messages simply by changing the arguments supplied.

Now if we look at the output of the ESM filter, notice that the severity level has been increased from 6 to 3:

%HSRP-3-STATECHANGE: FastEthernet0/0 Grp 1 state Standby -> Active

We have only looked at a few simple applications for the ESM. It is capable of doing so much more, and is only limited by the capabilities of TCL.