Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T Americas Headquarters

Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T Americas Headquarters
Embedded Syslog Manager Configuration
Guide, Cisco IOS Release 12.4T
Americas Headquarters
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706
USA
http://www.cisco.com
Tel: 408 526-4000
800 553-NETS (6387)
Fax: 408 527-0883
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS,
INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED
WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED
WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.
The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB’s public domain version
of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.
NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS” WITH ALL
FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE
PRACTICE.
IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING,
WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR
ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Cisco and the Cisco Logo are trademarks of Cisco Systems, Inc. and/or its affiliates in the U.S. and other countries. A listing of Cisco's trademarks can be found at www.cisco.com/go/
trademarks. Third party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any
other company. (1005R)
Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output,
network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content
is unintentional and coincidental.
© 2011 Cisco Systems, Inc. All rights reserved.
CONTENTS
Embedded Syslog Manager (ESM) 1
Finding Feature Information 1
Restrictions for Embedded Syslog Manager 1
Information About the Embedded Syslog Manager 2
Cisco IOS System Message Logging 2
System Logging Message Formatting 2
Embedded Syslog Manager 3
Syslog Filter Modules 3
How to Use the Embedded Syslog Manager 3
Writing ESM Syslog Filter Modules 4
The ESM Filter Process 4
Syslog Filter Module Input 4
Normal ESM Filter Processing 8
Background ESM Filter Processing 10
What to Do Next 11
Configuring the Embedded Syslog Manager 11
Configuration Examples for the Embedded Syslog Manager 14
Configuring the Embedded Syslog Manager Example 14
Syslog Filter Module Example 15
Severity Escalation Example 15
Message Counting Example 16
XML Tagging Example 19
SMTP-based E-mail Alert Example 20
Stream Example 21
Source IP Tagging Example 22
Additional References 22
Feature Information for Embedded Syslog Manager 24
Glossary 25
Logging to Local Nonvolatile Storage (ATA Disk) 27
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
iii
Contents
Finding Feature Information 27
Prerequisites for Logging to Local Nonvolatile Storage (ATA Disk) 27
Restrictions for Logging to Local Nonvolatile Storage (ATA Disk) 28
Information About Logging to Local Nonvolatile Storage (ATA Disk) 28
System Logging Messages 28
ATA Flash Disks 28
How to Configure Logging to Local Nonvolatile Storage (ATA Disk) 28
Writing Logging Messages to an ATA Disk 29
Copying Logging Messages to an External Disk 30
Configuration Examples for Logging to Local Nonvolatile Storage (ATA Disk) 30
Writing Logging Messages to an ATA Disk Example 30
Copying Logging Messages to an External Disk Example 30
Additional References 31
Feature Information for Logging to Local Nonvolatile Storage (ATA Disk) 32
Reliable Delivery and Filtering for Syslog 35
Finding Feature Information 35
Prerequisites for Reliable Delivery and Filtering for Syslog 35
Restrictions for Reliable Delivery and Filtering for Syslog 36
Information About Reliable Delivery and Filtering for Syslog 36
BEEP Transport Support 36
Syslog Message 37
Syslog Session 37
Multiple Syslog Sessions 38
Message Discriminator 39
Rate Limiting 40
Benefits of Reliable Delivery and Filtering for Syslog 41
How to Configure Reliable Delivery and Filtering for Syslog 41
Creating a Message Discriminator 41
Associating a Message Discriminator with a Logging Buffer 42
Associating a Message Discriminator with a Console Terminal 43
Associating a Message Discriminator with Terminal Lines 44
Enabling Message Counters 45
Adding and Removing a BEEP Session 46
Configuration Examples for Reliable Delivery and Filtering for Syslog 47
Configuring Transport and Logging Example 47
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
iv
Contents
Additional References 48
Feature Information for Reliable Delivery and Filtering for Syslog 49
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
v
Contents
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
vi
Embedded Syslog Manager (ESM)
The Embedded Syslog Manager (ESM) feature provides a programmable framework that allows you to
filter, escalate, correlate, route, and customize system logging messages prior to delivery by the Cisco IOS
system message logger.
•
•
•
•
•
•
•
•
Finding Feature Information, page 1
Restrictions for Embedded Syslog Manager, page 1
Information About the Embedded Syslog Manager, page 2
How to Use the Embedded Syslog Manager, page 3
Configuration Examples for the Embedded Syslog Manager, page 14
Additional References, page 22
Feature Information for Embedded Syslog Manager, page 24
Glossary, page 25
Finding Feature Information
Your software release may not support all the features documented in this module. For the latest feature
information and caveats, see the release notes for your platform and software release. To find information
about the features documented in this module, and to see a list of the releases in which each feature is
supported, see the Feature Information Table at the end of this document.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.
Restrictions for Embedded Syslog Manager
Embedded Syslog Manager (ESM) depends on the Tcl 8.3.4 Cisco IOS subsystem, as ESM filters are
written in Tool Command Language (Tcl). ESM is only available in images that support Tcl version 8.3.4
or later. Support for Tcl 8.3.4 is introduced in Cisco IOS Release 12.3(2)T.
ESM filters are written in Tcl. This document assumes the reader is familiar with Tcl programming.
ESM filtering cannot be applied to SNMP “history” logging. In other words, ESM filtering will not be
applied to messages logged using the logging history and snmp-server enable traps syslog commands.
Currently, the ESM filters do not support the debug messages. For example, if debug messages for IP
packets are enabled (with the debug ip packet command) and an ESM filter is used on the debug
messages, the filter will not work.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
1
Cisco IOS System Message Logging
Information About the Embedded Syslog Manager
Information About the Embedded Syslog Manager
•
•
•
•
Cisco IOS System Message Logging, page 2
System Logging Message Formatting, page 2
Embedded Syslog Manager, page 3
Syslog Filter Modules, page 3
Cisco IOS System Message Logging
The Cisco IOS system message logging (syslog) process allows the system to report and save important
error and notification messages, either locally or to a remote logging server. These syslog messages include
messages in a standardized format (called system logging messages, system error messages, or simply
system messages). These messages are generated during network operation to assist users and Cisco TAC
engineers with identifying the type and severity of a problem, or to aid users in monitoring router activity.
System logging messages can be sent to console connections, monitor (TTY) connections, the system
buffer, or to remote hosts.
With the introduction of the Embedded Syslog Manager, system messages can be logged independently as
standard messages, XML-formatted messages, or ESM filtered messages. These outputs can be sent to any
of the traditional syslog targets. For example, you could enable standard logging to the console connection,
XML-formatted message logging to the buffer, and ESM filtered message logging to the monitor.
Similarly, each type of output could be sent to different remote hosts. A benefit of separate logging
processes is that if, for example, there is some problem with the ESM filter modules, standard logging will
not be affected.
System Logging Message Formatting
System logging messages are displayed in the following format:
%<facility>-<severity>-<mnemonic>: <message-text>
For example:
%LINK-5-CHANGED: Interface Serial3/3, changed state to administratively down
Usually, these messages are preceded by additional text, such as the timestamp and error sequence number:
<sequence-number>: <timestamp>:%<facility>-<severity>-<mnemonic>: <message-text>
For example:
000013: Mar 18 14:52:10.039:%LINK-5-CHANGED: Interface Serial3/3, changed state
to administratively down
Note
The timestamp format used in system logging messages is determined by the service timestamps global
configuration mode command. The service sequence-numbers global configuration command enables or
disables the leading sequence number. An asterisk (*) before the time indicates that the time may be
incorrect because the system clock has not synchronized to a reliable time source.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
2
Embedded Syslog Manager
How to Use the Embedded Syslog Manager
Embedded Syslog Manager
The Embedded Syslog Manager (ESM) is a feature integrated in Cisco IOS software that allows complete
control over system message logging at the source. ESM provides a programmatic interface to allow you to
write custom filters that meet your specific needs in dealing with system logging. Benefits of this feature
include:
•
•
•
•
•
Customization--Fully customizable processing of system logging messages, with support for multiple,
interfacing syslog collectors.
Severity escalation for key messages--The ability to configure your own severity levels for syslog
messages instead of using the system-defined severity levels.
Specific message targeting--The ability to route specific messages or message types, based on type of
facility or type of severity, to different syslog collectors.
SMTP-base e-mail alerts--Capability for notifications using TCP to external servers, such as TCPbased syslog collectors or Simple Mail Transfer Protocol (SMTP) servers.
Message Limiting--The ability to limit and manage syslog “message storms” by correlating devicelevel events.
The ESM is not a replacement for the current UDP-based syslog mechanism; instead, it is an optional
subsystem that can operate in parallel with the current system logging process. For example, you can
continue to have the original syslog message stream collected by server A, while the filtered, correlated, or
otherwise customized ESM logging stream is sent to server B. All of the current targets for syslog
messages (console, monitor, buffer, and syslog host list) can be configured to receive either the original
syslog stream or the ESM stream. The ESM stream can be further divided into user-defined streams and
routed to collectors accordingly.
Syslog Filter Modules
To process system logging messages, the ESM uses syslog filter modules. Syslog filter modules are merely
scripts written in the Tcl script language stored in local system memory or on a remote file server. The
ESM is customizable because you can write and reference your own scripts.
Syslog filter modules can be written and stored as plain-text files or as precompiled files. Tcl script precompiling can be done with tools such as TclPro. Precompiled scripts allow a measure of security and
managed consistency because they cannot be edited.
Note
As Tcl script modules contain executable commands, you should manage the security of these files in the
same way you manage configuration files.
How to Use the Embedded Syslog Manager
•
•
Writing ESM Syslog Filter Modules, page 4
Configuring the Embedded Syslog Manager, page 11
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
3
Writing ESM Syslog Filter Modules
The ESM Filter Process
Writing ESM Syslog Filter Modules
Before referencing syslog filter modules in the ESM configuration, you must write or obtain the modules
you wish to apply to system logging messages. Syslog filter modules can be stored in local system memory,
or on a remote file server. To write syslog filter modules, you should understand the following concepts:
•
•
•
•
•
The ESM Filter Process, page 4
Syslog Filter Module Input, page 4
Normal ESM Filter Processing, page 8
Background ESM Filter Processing, page 10
What to Do Next, page 11
The ESM Filter Process
When ESM is enabled, all system logging messages are processed through the referenced syslog filter
modules. Syslog filter modules are processed in their order in the filter chain. The position of a syslog filter
module in the filter chain is determined by the position tag applied in the logging filter global
configuration mode command. If a position is not specified, the modules are processed in the order in
which they were added to the configuration.
The output of each filter module is used as the input for the next filter module in the chain. In other words,
the Tcl global variable containing the original syslog message (::orig_msg) is set to the return value of each
filter before calling the next filter in the chain. Thus, if a filter returns NULL, no message will be sent out
to the ESM stream. Once all filters have processed the message, the message is enqueued for distribution
by the logger.
The console, buffer, monitor, and syslog hosts can be configured to receive a particular message stream
(normal, XML, or ESM). The syslog hosts can be further restricted to receive user-defined numbered
streams. Each target examines each message and accepts or rejects the message based on its stream tag.
ESM filters can change the destination stream by altering the messages’ stream tag by changing the Tcl
global variable “::stream.”
Syslog Filter Module Input
When ESM is enabled, system logging messages are sent to the logging process. Each of the data elements
in the system logging message, as well as the formatted syslog message as a whole, are recorded as Tcl
global variables. The data elements format for the syslog message are as follows:
<sequence-number>: <timestamp>:%<facility>-<severity>-<mnemonic>: <message-text>
The message-text will often contain message-arguments.
When messages are received on a syslog host a “syslog-count” number is also added:
<syslog-count>: <sequence-number>: <timestamp>:%<facility>-<severity>-<mnemonic>: <message-text>
For example:
24:000024:02:18:37:%SYS-5-CONFIG_I:Configured from console by console
The table below lists the Tcl script input variables used in syslog filter modules. The syslog message data
that the filter must operate on are passed as Tcl global namespace variables. Therefore, variables should be
prefixed by a double-colon within the script module.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
4
Embedded Syslog Manager (ESM)
Syslog Filter Module Input
Table 1
Valid Variables for Syslog Filter Modules
Variable Name
Definition
::orig_msg
Full original system logging message as formatted
by the system.
•
::hostname
The router’s hostname.
•
::buginfseq
The timestamp format used in system logging
messages is determined by the service
timestamps global configuration mode
command.
The name of the system facility that generated the
message.
•
::severity
The service sequence-numbers global
configuration command enables or disables the
leading sequence number.
The timestamp on the system logging message.
•
::facility
The hostname can be added to the beginning of
syslog messages sent to remote hosts using the
logging origin-id hostname global
configuration mode command.
The error message sequence number.
•
::timestamp
If the filter module is just making decisions on
whether to send a message or not, return either
NULL or the value of this variable
($::orig_msg).
The FACILITY is a code consisting of two or
more uppercase letters that indicate the facility
to which the message refers. A facility can be a
hardware device, a protocol, or a module of the
system software. Common examples include
SYS, LINK, LINEPROTO, and so on.
The severity value.
•
•
The SEVERITY is a single-digit code from 0
to 7 that reflects the severity of the condition.
The lower the number, the more serious the
message.
The syslog filter module should change this
variable if the severity is to be escalated.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
5
Embedded Syslog Manager (ESM)
Syslog Filter Module Input
Variable Name
Definition
::mnemonic
The message mnemonic.
•
::format_string
The message-text string.
•
•
::msg_args
The format string is used to create the original
message. The message text will often contain
arguments; for example, in the message
“Configured from %s by %s,” %s indicates the
message arguments.
The message-text string is the message form
that can be passed to the Tcl format command.
The message-text arguments.
•
•
::process
The MNEMONIC is a code (usually an
abbreviated description) that uniquely
identifies the type of error or event. Common
examples include CONFIG_I, UPDOWN, and
so on.
The msg_args variable is the list containing the
arguments for the format_string.
For example, in the system logging message
“2w0d: %SYS-5-CONFIG_I: Configured from
console by console.” the format_string is
“Configured from %s by %s.” and the
msg_args are “console, console.”
The process name and interrupt level string.
•
Some system messages describe internal errors
and contain trace back information. The
following sample output shows the format for
process and interrupt level (ipl) information:
-Process= "Net Background", ipl= 2, pid= 82
::pid
The process ID (PID).
•
Some system messages include the process ID
of the triggering process. The following
sample output shows the format for process ID
(pid) information:
-Process= "Net Background", ipl= 2, pid=
12345
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
6
Embedded Syslog Manager (ESM)
Syslog Filter Module Input
Variable Name
Definition
::traceback
The traceback string.
•
Some system messages describe internal errors
and contain traceback information. This
information, when included, will typically
appear at the end of an error message. The
following sample output shows the format for
traceback information:
Apr 23 07:14:02: %ATMPA-3-CMDFAIL:
ATM2/1/0 Command Failed
at ../src-rsp/rsp_vip _atmdx.c - line 113,
arg 32784
-Process= "Net Background", ipl= 2, pid= 82
-Traceback= 602D12AC 602CED14 60050B6C
602CFF74
::syslog_facility
The syslog facility number used in the PRI portion
of the syslog message sent to external syslog
collectors (syslog hosts).
•
•
The syslog facility is given as a number, from
0 to 184.
The default is 184 (local7), but the value can
be changed with the logging facility global
configuration command.
::clear
Contains the string “- event cleared” or “NULL.”
::version
The Cisco IOS software version, in the format
“SYS_MAJORVERSION.
SYS_MINORVERSION.”
::module_position
The position of this syslog filter module in the filter
chain. The filter chain starts at one (1).
•
The value of this argument is determined by
the order in which the scripts are referenced by
the logging filter global configuration mode
command.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
7
Embedded Syslog Manager (ESM)
Normal ESM Filter Processing
Variable Name
Definition
::stream
The ESM message stream number.
•
•
•
The stream number will always be set to 2
(filtered stream) prior to the first filter being
executed.
Syslog filter modules can change this value to
a user-defined stream number in order to route
the message to particular syslog collectors.
Stream numbers are allocated as follows:
◦
◦
◦
◦
◦
::cli_args
Stream 0: Default (standard) syslog
stream
Stream 1: XML tagged syslog stream
Stream 2: Default filtered syslog stream
Streams 3-9: Reserved
Streams 10-65536: User defined
The list of optional arguments specified during the
filter configuration.
A Tcl list containing any optional filter arguments
specified when the filter was configured. This is the
list of strings specified after the args keyword when
the filter was configured with the logging filter
command.
::msg_part
The message part.
If an oversized syslog message has been split into
multiple messages, this variable contains a number
representing the message part (starting with 0).
::truncate
The incomplete message.
If an oversized syslog message has been split into
multiple messages, this variable will be nonzero if
this message is incomplete (truncated).
::sev_prefix
The severity prefix string.
Contains the optional severity prefix string.
::msg_prefix
The message prefix string.
Contains the optional message prefix string.
::fac_prefix
The optional facility prefix string.
Contains the optional facility prefix string.
Normal ESM Filter Processing
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
8
Embedded Syslog Manager (ESM)
Normal ESM Filter Processing
Each time a system logging message is generated, the syslog filter modules are called in a series. This
series is determined by the ::module_position variable, which in turn is typically the order in which the
modules are referenced in the system configuration (the order in which they are configured).
The output of one filter module becomes the input to the next. Because the input to the filters are the Tcl
global namespace variables (as listed in Normal ESM Filter Processing, page 8), each filter can change any
or all of these variables depending upon the purpose of the filter.
The only Tcl global variables that are automatically updated by the ESM framework between subsequent
filter executions are the ::orig_msg and ::cli_args variables. The framework automatically sets the value
of ::orig_msg to the return value of the filter module. Thus a filter that is designed to alter or filter the
original message must not manually set the value for the ::orig_msg variable; the filter only needs to return
the desired value. For example, the following one-line ESM filter
return “This is my new syslog message.”
would ignore any message passed to it, and always change the output to the constant string “This is my new
syslog message.” If the module was the last filter in the chain, all ESM targets would receive this string as
the final syslog message.
The one-line ESM filter
return “”
would block all syslog messages to the ESM stream. For example, the line
return $::orig_msg
would do nothing but pass the message along to the next filter in the chain. Thus, an ESM filter designed to
suppress unwanted messages would look something like this:
if { [my_procedure_to_check_this_message] == 1 } {
return $::orig_msg
} else {
return “”
}
Depending upon their design, some filters may not use the ::orig_msg variable at all, but rather reconstruct
a syslog message from its data elements (using ::format_string, ::msg_args, ::timestamp, and so on). For
example, an XML tagging filter will tag the individual data elements, and disregard the original formatted
message. It is important for such modules to check the ::orig_msg variable at the beginning of the Tcl
script, so that if previous filter indicated that the message should not be sent out (::orig_msg is NULL), it
would not bother to process the message, but simply return NULL also.
Cisco IOS commands can also be added to syslog filter modules using the exec and config Tcl commands.
For example, if you wanted to add the source IP address to the syslog messages, and syslog messages were
configured to be sent from the Ethernet 2/0 interface (using the logging source-interface command) you
could issue the show interface Ethernet 2/0 command during the module initialization by using the exec
Tcl command within the script:
set source_ip_string [exec show ip int E2/0 | inc Internet]
puts $source_ip_string
" Internet address is 10.4.2.63/24"
The script should then pass the output of that command to the syslog message. For further information on
scripting within Cisco IOS software, see the “Cisco IOS Scripting with Tcl” feature module on Cisco.com.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
9
Embedded Syslog Manager (ESM)
Background ESM Filter Processing
Background ESM Filter Processing
In Tcl it is possible to queue commands for processing in the future by using the after Tcl command. The
most common use of this command is to correlate (gather and summarize) events over a fixed interval of
time, called the “correlation window.” Once the window of interest expires, the filter will need to “wake
up,” and calculate or summarize the events that occurred during the window, and often send out a new
syslog message to report the events. This background process is handled by the ESM Event Loop process,
which allows the Tcl interpreter to execute queued commands after a certain amount of time has passed.
If your syslog filter module needs to take advantage of correlation windows, it must use the after Tcl
command to call a summary procedure once the correlation window expires (see examples in the
Configuration Examples for the Embedded Syslog Manager, page 14). Because there is no normal filter
chain processing when background processes are run, in order to produce output these filters must make
use of one of two ESM Tcl extensions: errmsg or esm_errmsg.
During background processing, the commands that have been enqueued by the after command are not run
in the context of the filter chain (as in normal processing), but rather are autonomous procedures that are
executed in series by the Tcl interpreter. Thus, these background procedures should not operate on the
normal Tcl global namespace variables (except for setting the global namespace variables for the next filter
when using esm_errmsg), but should operate on variables stored in their own namespace. If these variables
are declared outside of a procedure definition, they will be persistent from call to call.
The purpose of the errmsg Tcl command is to create a new message and send it out for distribution,
bypassing any other syslog filter modules. The syntax of the errmsg command is:
errmsg <severity> <stream> <message_string>
The purpose of the esm_errmsg Tcl command is to create a new message, process it with any syslog filter
modules below it in the filter chain, and then send it out for distribution. The syntax of the esm_errmsg
command is:
esm_errmsg <module_position>
The key difference between the errmsg() Tcl function and the esm_errmsg() Tcl function is that errmsg
ignores the filters and directly queues a message for distribution, while esm_errmsgwill send a syslog
message down the chain of filters.
In the following example, a new syslog message is created and sent out tagged as Alert severity 1 to the
configured ESM logging targets (stream 2). One can assume the purpose of this filter would be to suppress
the individual SYS-5-CONFIG messages over a thirty minute correlation window, and send out a summary
message at the end of the window.
errmsg 1 2 “*Jan 24 09:34:02.539: %SYS-1-CONFIG_I: There have been 12
configuration changes to the router between Jan 24 09:04:02.539 and Jan 24
09:34:01.324”
In order to use esm_errmsg, because the remaining filters below this one will be called, this background
process must populate the needed Tcl global namespace variables prior to calling esm_errmsg. Passing
the ::module_position tells the ESM framework which filter to start with. Thus, filters using the
esm_errmsg command should store their ::module_position (passed in the global namespace variables
during normal processing) in their own namespace variable for use in background processing. Here is an
example:
proc ::my_filter_namespace::my_summary_procedure{}
{
set ::orig_msg “*Jan 24 09:34:02.539: %SYS-1-CONFIG_I: There have been 12
configuration changes to the router between Jan 24 09:04:02.539 and Jan 24
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
10
Configuring the Embedded Syslog Manager
What to Do Next
09:34:01.324”
set ::timestamp “*Jan 24 09:34:02.539”
set ::severity 1
set ::stream 2
set ::traceback “”
set ::pid “”
set ::process “”
set ::format_string “There have been %d configuration changes to the router
between %s and %s”
set ::msg_args {12 “Jan 24 09:04:01.539” “Jan 24 09:34:01.324”}
esm_errmsg $::my_filter_namespace::my_module_position
}
The benefit of setting all the global namespace variables for the esm_errmsg command is that your filters
will be modular, and it will not matter what order they are used in the ESM framework. For example, if you
wish all of the messages destined for the ESM targets to suffixed with the message originator’s hostname,
you could write a one-line “hostname” filter and place it at the bottom of the filter chain:
return “$::orig_msg -- $::hostname”
In this example, if any of your filters generate new messages during background processing and they use
esm_errmsg instead of errmsg, these messages will be clearly suffixed with the hostname.
What to Do Next
After creating your syslog filter module, you should store the file in a location accessible to the router. You
can copy the file to local system memory, or store it on a network file server.
Configuring the Embedded Syslog Manager
To configure the ESM, specify one or more filters to be applied to generated syslog messages, and specify
the syslog message target.
One or more syslog filter modules must be available to the router.
SUMMARY STEPS
1. enable
2. configure terminal
3. logging filter filter-url [position] [args filter-arguments]
4. Repeat Step 3 for each syslog filter module that should be applied to system logging output.
5. Do one of the following:
•
•
•
•
•
logging [console | buffered | monitor] filtered [level]
or
logging host {ip-address | host-name} filtered [stream stream-id]
6. Repeat Step 5 for each desired system logging destination.
7. logging source-interface type number
8. logging origin-id {hostname | ip | string user-defined-id}
9. end
10. show logging
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
11
Embedded Syslog Manager (ESM)
What to Do Next
DETAILED STEPS
Command or Action
Step 1 enable
Purpose
Enables privileged EXEC mode.
•
Enter your password if prompted.
Example:
Router> enable
Step 2 configure terminal
Enters global configuration mode.
Example:
Router# configure terminal
Step 3 logging filter filter-url [position] [args Specifies one or more syslog filter modules to be applied to generated system
logging messages.
filter-arguments]
Example:
Router(config)# logging filter
slot0:/escalate.tcl 1 args
CONFIG_I 1
•
•
•
•
•
•
Step 4 Repeat Step 3 for each syslog filter
module that should be applied to
system logging output.
Repeat this command for each syslog filter module that should be used.
The filter-url argument is the Cisco IOS File System location of the syslog
filter module (script). The location can be in local memory, or a remote
server using tftp:, ftp:, or rcp:.
The optional position argument specifies the order in which the syslog
filter modules should be executed. If this argument is omitted, the specified
module will be positioned as the last module in the chain.
Filters can be re-ordered on the fly by re-entering the logging filter
command and specifying a different position.
The optional args filter-arguments syntax can be added to pass arguments
to the specified filter. Multiple arguments can be specified. The number
and type of arguments should be defined in the syslog filter module. For
example, if the syslog filter module is designed to accept a specific e-mail
address as an argument, you could pass the e-mail address using the args
user@host.com syntax.Multiple arguments are typically delimited by
spaces.
To remove a module from the list of modules to be executed, use the no
form of this command.
--
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
12
Embedded Syslog Manager (ESM)
What to Do Next
Command or Action
Step 5 Do one of the following:
•
•
•
•
logging [console | buffered |
monitor] filtered [level]
Purpose
Specifies the target for ESM filtered syslog output.
•
•
or
logging host {ip-address | hostname} filtered [stream streamid]
•
•
Example:
Router(config)# logging console
filtered informational
•
Example:
•
Example:
ESM filtered syslog messages can be sent to the console, a monitor (TTY
and Telnet connections), the system buffer, or to remote hosts.
The optional level argument limits the sending of messages to those at or
numerically lower than the specified value. For example, if level 1 is
specified, only messages at level 1 (alerts) or level 0 (emergencies) will be
sent to the specified target. The level can be specified as a keyword or
number.
When logging to the console, monitor connection, or system buffer, the
severity threshold specified by the level argument takes precedence over
the ESM filtering. In other words, even if the ESM filters return a message
to be delivered to ESM targets, if the severity doesn’t meet the configured
threshold (is numerically higher than the level value), it will not be
delivered.
When logging to remote hosts, the stream tag allows you to specify a
destination based on the type of message. The stream stream-id syntax
allows you to configure the ESM to send only messages that have a
specified stream value to a certain host.
The stream value is applied to messages by the configured syslog filter
modules. For example, all Severity 5 messages could have a stream tag of
“20” applied. You can then specify that all messages with a stream tag of
“20” be sent to the host at 209.165.200.225.:
Router(config)# logging host
209.165.200.225 filtered stream
20
Step 6 Repeat Step 5 for each desired system
logging destination.
•
•
By issuing the logging host command multiple times, you can specify
different targets for different system logging streams.
Similarly, you can configure messages at different severity levels to be sent
to the console, monitor connection, or system buffer. For example, you
may want to display only very important messages to the screen (using a
monitor or console connection) at your network operations center (NOC).
Step 7 logging source-interface type number (Optional) Specifies the source interface for syslog messages sent to remote
syslog hosts.
Example:
Router(config)# logging sourceinterface ethernet 0
•
Normally, a syslog messages sent to remote hosts will use whatever
interface is available at the time of the message generation. This command
forces the router to send syslog messages to remote hosts only from the
specified interface.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
13
Configuring the Embedded Syslog Manager Example
Configuration Examples for the Embedded Syslog Manager
Command or Action
Step 8 logging origin-id {hostname | ip |
string user-defined-id}
Purpose
(Optional) Allows you to add an origin identifier to syslog messages sent to
remote hosts.
•
Example:
Router(config)# logging originid string “Domain 2, Router 5”
•
The origin identifier is added to the beginning of all syslog messages sent
to remote hosts. The identifier can be the hostname, the IP address, or any
text that you specify.
The origin identifier is useful for identifying the source of system logging
messages in cases where you send syslog output from multiple devices to a
single syslog host.
Example:
Step 9 end
Ends your current configuration session and returns the CLI to privileged EXEC
mode.
Example:
Router(config)# end
Step 10 show logging
(Optional) Displays the status of system logging, including the status of ESM
filtered logging.
Example:
•
Router# show logging
•
If filtered logging to the buffer is enabled, this command also shows the
data stored in the buffer.
The order in which syslog filter modules are listed in the output of this
command is the order in which the filter modules are executed.
Example:
Example:
Configuration Examples for the Embedded Syslog Manager
•
•
Configuring the Embedded Syslog Manager Example, page 14
Syslog Filter Module Example, page 15
Configuring the Embedded Syslog Manager Example
In the following example, ESM filter logging is enabled for the console connection, standard logging is
enabled for the monitor connection and for the buffer, and XML-formatted logging is enabled for the host
at 209.165.200.225:
Router(config)# logging filter tftp://209.165.200.225/ESM/escalate.tcl
Router(config)# logging filter slot0:/email.tcl user@example.com
Router(config)# logging filter slot0:/email_guts.tcl
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
14
Syslog Filter Module Example
Severity Escalation Example
Router(config)# logging console filtered
Router(config)# logging monitor 4
Router(config)# logging buffered debugging
Router(config)# logging host 209.165.200.225 xml
Router(config)# end
Router# show logging
Syslog logging: enabled (0 messages dropped, 8 messages rate-limited,
0 flushes, 0 overruns, xml disabled, filtering enabled)
Console logging: level debugging, 21 messages logged, xml disabled,
filtering enabled
Monitor logging: level warnings , 0 messages logged, xml disabled,
filtering disabled
Buffer logging: level debugging, 30 messages logged, xml disabled,
filtering disabled
Logging Exception size (8192 bytes)
Count and timestamp logging messages: disabled
Filter modules:
tftp://209.165.200.225/ESM/escalate.tcl
slot0:/email.tcl user@example.com
Trap logging: level informational, 0 message lines logged
Logging to 209.165.200.225, 0 message lines logged, xml enabled,
filtering disabled
Log Buffer (8192 bytes):
*Jan 24 09:34:28.431: %SYS-5-CONFIG_I: Configured from console by console
*Jan 24 09:34:51.555: %SYS-5-CONFIG_I: Configured from console by console
*Jan 24 09:49:44.295: %SYS-5-CONFIG_I: Configured from console by console
Router#
Syslog Filter Module Example
Syslog Script Modules are Tcl scripts. The following examples are provided to assist you in developing
your own Syslog Script Modules.
Note
These script modules are provided as examples only, and are not supported by Cisco Systems, Inc. No
guarantees, expressed or implied, are provided for the functionality or impact of these scripts.
This appendix contains the following syslog filter module examples:
•
•
•
•
•
•
Severity Escalation Example, page 15
Message Counting Example, page 16
XML Tagging Example, page 19
SMTP-based E-mail Alert Example, page 20
Stream Example, page 21
Source IP Tagging Example, page 22
Severity Escalation Example
This ESM syslog filter module example watches for a single mnemonic (supplied via the first CLI
argument) and escalates the severity of the message to that specified by the second CLI argument.
#
#
#
#
#
#
===================================================================
Embedded Syslog Manager
||
||
||
||
Severity Escalation Filter
||||
||||
..:||||||:..:||||||:..
------------------------
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
15
Embedded Syslog Manager (ESM)
Message Counting Example
#
C i s c o S y s t e m s
# ====================================================================
#
# Usage: Set CLI Args to "mnemonic new_severity"
#
# Namespace: global
# Check for null message
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
Message Counting Example
This ESM syslog filter module example is divided into two files for readability. The first file allows the
user to configure those messages that they wish to count and how often to summarize (correlation window)
by populating the msg_to_watch array. The actual procedures are in the counting_guts.tcl file. Note the use
of the separate namespace “counting” to avoid conflict with other ESM filters that may also perform
background processing.
#
#
#
#
#
#
#
===================================================================
Embedded Syslog Manager
||
||
||
||
Message Counting Filter
||||
||||
..:||||||:..:||||||:..
-----------------------C i s c o S y s t e m s
# ====================================================================
#
# Usage:
# 1) Define the location for the counting_guts.tcl script
#
# 2) Define message categories to count and how often to dump them (sec)
#
by populating the "msg_to_watch" array below.
#
Here we define category as facility-severity-mnemonic
#
Change dump time to 0 to disable counting for that category
#
# Namespace: counting
namespace eval ::counting {
set sub_script_url tftp://123.123.123.123/ESM/counting_guts.tcl
array set msg_to_watch {
SYS-5-CONFIG_I
5
}
# ======================= End User Setup ==============================
# Initialize processes for counting
if { [info exists init] == 0 } {
source $sub_script_url
set position $module_position
}
# Process the message
process_category
} ;# end namespace counting
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
16
Embedded Syslog Manager (ESM)
Message Counting Example
Message Counting Support Module (counting_guts.tcl)
#
#
#
#
#
#
#
===================================================================
Embedded Syslog Manager
||
||
||
||
Message Counting Support Module
||||
||||
..:||||||:..:||||||:..
(No User Modification)
-----------------------C i s c o S y s t e m s
# ====================================================================
namespace eval ::counting {
# namespace variables
array
array
array
array
array
array
array
array
array
array
array
array
set
set
set
set
set
set
set
set
set
set
set
set
cat_msg_sev {}
cat_msg_traceback {}
cat_msg_pid {}
cat_msg_proc {}
cat_msg_ts {}
cat_msg_buginfseq {}
cat_msg_name {}
cat_msg_fac {}
cat_msg_format {}
cat_msg_args {}
cat_msg_count {}
cat_msg_dump_ts {}
# Should I count this message ?
proc query_category {cat} {
variable msg_to_watch
if { [info exists msg_to_watch($cat)] } {
return $msg_to_watch($cat)
} else {
return 0
}
}
proc clear_category {index} {
variable cat_msg_sev
variable cat_msg_traceback
variable cat_msg_pid
variable cat_msg_proc
variable cat_msg_ts
variable cat_msg_buginfseq
variable cat_msg_name
variable cat_msg_fac
variable cat_msg_format
variable cat_msg_args
variable cat_msg_count
variable cat_msg_dump_ts
unset cat_msg_sev($index) cat_msg_traceback($index) cat_msg_pid($index)\
cat_msg_proc($index) cat_msg_ts($index) \
cat_msg_buginfseq($index) cat_msg_name($index) \
cat_msg_fac($index) cat_msg_format($index) cat_msg_args($index)\
cat_msg_count($index) cat_msg_dump_ts($index)
}
# send out the counted messages
proc dump_category {category} {
variable cat_msg_sev
variable cat_msg_traceback
variable cat_msg_pid
variable cat_msg_proc
variable cat_msg_ts
variable cat_msg_buginfseq
variable cat_msg_name
variable cat_msg_fac
variable cat_msg_format
variable cat_msg_args
variable cat_msg_count
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
17
Embedded Syslog Manager (ESM)
Message Counting Example
variable cat_msg_dump_ts
variable poll_interval
set dump_timestamp [cisco_service_timestamp]
foreach index [array names cat_msg_count $category] {
set fsm "$cat_msg_fac($index)-$cat_msg_sev($index)-$cat_msg_name($index)"
set ::orig_msg \
[format "%s%s: %%%s: %s %s %s %s - (%d occurence(s) between %s and %s)"\
$cat_msg_buginfseq($index)\
$dump_timestamp\
$fsm \
[uplevel 1 [linsert $cat_msg_args($index) 0 ::format
$cat_msg_format($index) ]] \
$cat_msg_pid($index) \
$cat_msg_proc($index) \
$cat_msg_traceback($index) \
$cat_msg_count($index) \
$cat_msg_ts($index) \
$dump_timestamp]
# Prepare for remaining ESM filters
set ::severity $cat_msg_sev($index)
set ::traceback $cat_msg_traceback($index)
set ::pid $cat_msg_pid($index)
set ::process $cat_msg_proc($index)
set ::timestamp $cat_msg_ts($index)
set ::buginfseq $cat_msg_buginfseq($index)
set ::mnemonic $cat_msg_name($index)
set ::facility $cat_msg_fac($index)
set ::format_string $cat_msg_format($index)
set ::msg_args [split $cat_msg_args($index)]
esm_errmsg $counting::position
clear_category $index
}
}
# See if this message already has come through since the last dump.
# If so, increment the count, otherwise store it.
proc process_category {} {
variable cat_msg_sev
variable cat_msg_traceback
variable cat_msg_pid
variable cat_msg_proc
variable cat_msg_ts
variable cat_msg_buginfseq
variable cat_msg_name
variable cat_msg_fac
variable cat_msg_format
variable cat_msg_args
variable cat_msg_count
variable cat_msg_dump_ts
if { [string length $::orig_msg] == 0} {
return ""
}
set category "$::facility-$::severity-$::mnemonic"
set correlation_window [expr [ query_category $category ] * 1000]
if { $correlation_window == 0 } {
return $::orig_msg
}
set message_args [join $::msg_args]
set index "$category,[lindex $::msg_args 0]"
if { [info exists cat_msg_count($index)] } {
incr cat_msg_count($index)
} else {
set cat_msg_sev($index) $::severity
set cat_msg_traceback($index) $::traceback
set cat_msg_pid($index) $::pid
set cat_msg_proc($index) $::process
set cat_msg_ts($index) $::timestamp
set cat_msg_buginfseq($index) $::buginfseq
set cat_msg_name($index) $::mnemonic
set cat_msg_fac($index) $::facility
set cat_msg_format($index) $::format_string
set cat_msg_args($index) $message_args
set cat_msg_count($index) 1
set cat_msg_dump_ts($index) [clock seconds]
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
18
Embedded Syslog Manager (ESM)
XML Tagging Example
catch [after $correlation_window counting::dump_category $index]
}
return ""
}
# Initialized
set init 1
} ;#end namespace counting
XML Tagging Example
This ESM syslog filter module applies user-defined XML tags to syslog messages.
# ===================================================================
# Embedded Syslog Manager
||
||
#
||
||
# XML Tagging Filter
||||
||||
#
..:||||||:..:||||||:..
#
-----------------------#
C i s c o S y s t e m s
# ===================================================================
#
# Usage: Define desired tags below.
#
# Namespace: xml
# Check for null message
if { [string length $::orig_msg] == 0} {
return ""
}
namespace eval xml {
#### define tags ####
set MSG_OPEN "<ios-log-msg>"
set MSG_CLOSE "</ios-log-msg>"
set FAC_OPEN
"<facility>"
set FAC_CLOSE "</facility>"
set SEV_OPEN
"<severity>"
set SEV_CLOSE "</severity>"
set MNE_OPEN
"<msg-id>"
set MNE_CLOSE "</msg-id>"
set SEQ_OPEN
"<seq>"
set SEQ_CLOSE "</seq>"
set TIME_OPEN "<time>"
set TIME_CLOSE "</time>"
set ARGS_OPEN "<args>"
set ARGS_CLOSE "</args>"
set ARG_ID_OPEN "<arg id="
set ARG_ID_CLOSE "</arg>"
set PROC_OPEN "<proc>"
set PROC_CLOSE "</proc>"
set PID_OPEN "<pid>"
set PID_CLOSE "</pid>"
set TRACE_OPEN "<trace>"
set TRACE_CLOSE "</trace>"
# ======================= End User Setup ==============================
#### clear result ####
set result ""
#### message opening, facility, severity, and name ####
append result $MSG_OPEN $FAC_OPEN $::facility $FAC_CLOSE $SEV_OPEN $::severity
$SEV_CLOSE $MNE_OPEN $::mnemonic $MNE_CLOSE
#### buginf sequence numbers ####
if { [string length $::buginfseq ] > 0 } {
append result $SEQ_OPEN $::buginfseq $SEQ_CLOSE
}
#### timestamps ####
if { [string length $::timestamp ] > 0 } {
append result $TIME_OPEN $::timestamp $TIME_CLOSE
}
#### message args ####
if { [info exists ::msg_args] } {
if { [llength ::msg_args] > 0 } {
set i 0
append result $ARGS_OPEN
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
19
Embedded Syslog Manager (ESM)
SMTP-based E-mail Alert Example
foreach arg $::msg_args {
append result $ARG_ID_OPEN $i ">" $arg $ARG_ID_CLOSE
incr i
}
append result $ARGS_CLOSE
}
}
#### traceback ####
if { [string length $::traceback ] > 0 } {
append result $TRACE_OPEN $::traceback $TRACE_CLOSE
}
#### process ####
if { [string length $::process ] > 0 } {
append result $PROC_OPEN $::process $PROC_CLOSE
}
#### pid ####
if { [string length $::pid ] > 0 } {
append result $PID_OPEN $::pid $PID_CLOSE
}
#### message close ####
append result $MSG_CLOSE
return "$result"
} ;# end namespace xml
SMTP-based E-mail Alert Example
This ESM syslog filter module example watches for configuration messages and sends them to the e-mail
address supplied as a CLI argument. This filter is divided into two files. The first file implements the filter,
and the second file implements the SMTP client.
# ===================================================================
# Embedded Syslog Manager
||
||
#
||
||
# Email Filter
||||
||||
# (Configuration Change Warning)
..:||||||:..:||||||:..
#
-----------------------#
C i s c o S y s t e m s
#
===================================================================
# Usage: Provide email address as CLI argument. Set email server IP in
#
email_guts.tcl
#
# Namespace: email
if { [info exists email::init] == 0 } {
source tftp://123.123.123.123/ESM/email_guts.tcl
}
# Check for null message
if { [string length $::orig_msg] == 0} {
return ""
}
if { [info exists ::msg_args] } {
if { [string compare -nocase CONFIG_I $::mnemonic ] == 0 } {
email::sendmessage $::cli_args $::mnemonic \
[string trim $::orig_msg]
}
}
return $::orig_msg
E-mail Support Module (email_guts.tcl)
# ===================================================================
# Embedded Syslog Manager
||
||
#
||
||
# Email Support Module
||||
||||
#
..:||||||:..:||||||:..
#
-----------------------#
C i s c o S y s t e m s
#
===================================================================
#
# Usage: Set email host IP, from, and friendly strings below.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
20
Embedded Syslog Manager (ESM)
Stream Example
#
namespace eval email {
set sendmail(smtphost) 64.102.17.214
set sendmail(from) $::hostname
set sendmail(friendly) $::hostname
proc sendmessage {toList subject body} {
variable sendmail
set smtphost $sendmail(smtphost)
set from $sendmail(from)
set friendly $sendmail(friendly)
set sockid [socket $smtphost 25]
## DEBUG
set status [catch {
puts $sockid "HELO $smtphost"
flush $sockid
set result [gets $sockid]
puts $sockid "MAIL From:<$from>"
flush $sockid
set result [gets $sockid]
foreach to $toList {
puts $sockid "RCPT To:<$to>"
flush $sockid
}
set result [gets $sockid]
puts $sockid "DATA "
flush $sockid
set result [gets $sockid]
puts $sockid "From: $friendly <$from>"
foreach to $toList {
puts $sockid "To:<$to>"
}
puts $sockid "Subject: $subject"
puts $sockid "\n"
foreach line [split $body "\n"] {
puts $sockid " $line"
}
puts $sockid "."
puts $sockid "QUIT"
flush $sockid
set result [gets $sockid]
} result]
catch {close $sockid }
if {$status} then {
return -code error $result
}
}
} ;# end namespace email
set email::init 1
Stream Example
This ESM syslog filter module example watches for a given facility (first CLI argument) and routes these
messages to a given stream (second CLI argument).
# ===================================================================
# Embedded Syslog Manager
||
||
#
||
||
# Stream Filter (Facility)
||||
||||
#
..:||||||:..:||||||:..
#
-----------------------#
C i s c o S y s t e m s
#
===================================================================
# Usage: Provide facility and stream as CLI arguments.
#
# Namespace: global
# Check for null message
# ======================= End User Setup ==============================
set args [split $::cli_args]
if { [info exists ::msg_args] } {
if { $::facility == [lindex $args 0] } {
set ::stream [lindex $args 1]
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
21
Embedded Syslog Manager (ESM)
Source IP Tagging Example
}
}
return $::orig_msg}
Source IP Tagging Example
The logging source-interface CLI command can be used to specify a source IP address in all syslog
packets sent from the router. The following syslog filter module example demonstrates the use of show CLI
commands (show running-config and show ip interface in this case) within a filter module to add the
source IP address to syslog messages. The scriptlooks for the local namespace variable “source_ip::init”
first. If the variable is not defined in the first syslog message processed, the filter will run the show
commands and use regular expressions to get the source-interface and then its IP address.
Note that in this script, the show commands are only run once. If the source-interface or its IP address were
to be changed, the filter would have to be re-initialized to pick up the new information. (You could have the
show commands run on every syslog message, but this would not scale very well.)
# ===================================================================
# Embedded Syslog Manager
||
||
#
||
||
# Source IP Module
||||
||||
#
..:||||||:..:||||||:..
#
-----------------------#
C i s c o S y s t e m s
#
===================================================================
# Usage: Adds Logging Source Interface IP address to all messages.
#
# Namespace:source_ip
#
# ======================= End User Setup ==============================
namespace eval ::source_ip {
if { [info exists init] == 0 } {
if { [catch {regexp {^logging source-interface (.*$)} [exec show
run | inc logging source-interface] match source_int}]} {
set suffix "No source interface specified"
} elseif { [catch {regexp {Internet address is (.*)/.*$} [exec
show ip int $source_int | inc Internet] match ip_addr}]} {
set suffix "No IP address configured for source interface"
} else {
set suffix $ip_addr
}
set init 1
}
if { [string length $::orig_msg] == 0} {
return ""
}
return "$::orig_msg - $suffix"
} ;# end namespace source_ip
Additional References
The following sections provide references related to the Embedded Syslog Manager feature.
Related Documents
Related Topic
Document Title
System Message Logging
Troubleshooting and Fault Management module
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
22
Embedded Syslog Manager (ESM)
Additional References
Related Topic
Document Title
XML Formatted System Message Logging
XML Interface to Syslog Messages module
Tcl 8.3.4 Support in Cisco IOS Software
Cisco IOS Scripting with Tcl module
Network Management commands (including
logging commands): complete command syntax,
defaults, command mode, command history, usage
guidelines, and examples
Cisco IOS Network Management Command
Reference
Standards
Standard
Title
No new or modified standards are supported, and
support for existing standards has not been
modified.
--
MIBs
MIB
MIBs Link
No new or modified standards are supported, and
support for existing standards has not been
modified.
To locate and download MIBs for selected
platforms, Cisco IOS releases, and feature sets, use
Cisco MIB Locator found at the following URL:
http://www.cisco.com/go/mibs
RFCs
RFCs1
Title
RFC-3164
The BSD Syslog Protocol
•
This RFC is informational only. The Cisco
implementation of syslog does not claim full
compliance with the protocol guidelines
mentioned in this RFC.
1 Not all supported RFCs are listed.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
23
Embedded Syslog Manager (ESM)
Feature Information for Embedded Syslog Manager
Technical Assistance
Description
Link
The Cisco Support website provides extensive
http://www.cisco.com/techsupport
online resources, including documentation and tools
for troubleshooting and resolving technical issues
with Cisco products and technologies.
To receive security and technical information about
your products, you can subscribe to various
services, such as the Product Alert Tool (accessed
from Field Notices), the Cisco Technical Services
Newsletter, and Really Simple Syndication (RSS)
Feeds.
Access to most tools on the Cisco Support website
requires a Cisco.com user ID and password.
Feature Information for Embedded Syslog Manager
The following table provides release information about the feature or features described in this module.
This table lists only the software release that introduced support for a given feature in a given software
release train. Unless noted otherwise, subsequent releases of that software release train also support that
feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.
Table 2
Feature Information for Embedded Syslog Manager
Feature Name
Releases
Feature Information
Embedded Syslog Manager
12.3(2)T 12.3(2)XE 12.2(25)S
12.2(33)SRC 12.2(33)SB
12.2(33)SXI
The Embedded Syslog Manager
(ESM) feature provides a
programmable framework that
allows you to filter, escalate,
correlate, route, and customize
system logging messages prior to
delivery by the Cisco IOS system
message logger.
The following commands were
introduced or modified: logging
buffered filtered, logging
console filtered, logging filter,
logging host, logging monitor
filtered, logging origin-id, show
logging.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
24
Embedded Syslog Manager (ESM)
Glossary
Glossary
Note
Refer to the Internetworking Terms and Acronyms for terms not included in this glossary.
console --In the context of this feature, specifies the connection (CTY or console line) to the console port
of the router. Typically, this is a terminal attached directly to the console port, or a PC with a terminal
emulation program. Corresponds to the show terminal command.
monitor --In the context of this feature, specifies the TTY (TeleTYpe terminal) line connection at a line
port. In other words, the “monitor” keyword corresponds to a terminal line connection or a Telnet (terminal
emulation) connection. TTY lines (also called ports) communicate with peripheral devices such as
terminals, modems, and serial printers. An example of a TTY connection is a PC with a terminal emulation
program connected to the device using a dial-up modem.
SEMs --Abbreviation for system error messages. “System error messages” is the term formerly used for
messages generated by the system logging (syslog) process. Syslog messages use a standardized format,
and come in 8 severity levels, from “emergencies” (level 0) to “debugging” (level 7). The term “system
error message” is actually misleading, as these messages can include notifications of router activity beyond
“errors” (such as informational notices).
syslog --Abbreviation for the system message logging process in Cisco IOS software. Also used to identify
the messages generated, as in “syslog messages.” Technically, the term “syslog” refers only to the process
of logging messages to a remote host or hosts, but is commonly used to refer to all Cisco IOS system
logging processes.
trap --A trigger in the system software for sending error messages. In the context of this feature, “trap
logging” means logging messages to a remote host. The remote host is actually a syslog host from the
perspective of the device sending the trap messages, but because the receiving device typically provides
collected syslog data to other devices, the receiving device is also referred to as a “syslog server.”
Cisco and the Cisco Logo are trademarks of Cisco Systems, Inc. and/or its affiliates in the U.S. and other
countries. A listing of Cisco's trademarks can be found at www.cisco.com/go/trademarks. Third party
trademarks mentioned are the property of their respective owners. The use of the word partner does not
imply a partnership relationship between Cisco and any other company. (1005R)
Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be
actual addresses and phone numbers. Any examples, command display output, network topology diagrams,
and other figures included in the document are shown for illustrative purposes only. Any use of actual IP
addresses or phone numbers in illustrative content is unintentional and coincidental.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
25
Syslog Filter Module Example
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
26
Logging to Local Nonvolatile Storage (ATA
Disk)
The Logging to Local Nonvolatile Storage (ATA Disk) feature enables system logging messages to be
saved on an advanced technology attachment (ATA) flash disk. Messages saved on an ATA drive persist
after a router is rebooted.
•
•
•
•
•
•
•
•
Finding Feature Information, page 27
Prerequisites for Logging to Local Nonvolatile Storage (ATA Disk), page 27
Restrictions for Logging to Local Nonvolatile Storage (ATA Disk), page 28
Information About Logging to Local Nonvolatile Storage (ATA Disk), page 28
How to Configure Logging to Local Nonvolatile Storage (ATA Disk), page 28
Configuration Examples for Logging to Local Nonvolatile Storage (ATA Disk), page 30
Additional References, page 31
Feature Information for Logging to Local Nonvolatile Storage (ATA Disk), page 32
Finding Feature Information
Your software release may not support all the features documented in this module. For the latest feature
information and caveats, see the release notes for your platform and software release. To find information
about the features documented in this module, and to see a list of the releases in which each feature is
supported, see the Feature Information Table at the end of this document.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.
Prerequisites for Logging to Local Nonvolatile Storage (ATA
Disk)
The logging buffered Command Must Be Enabled
Before the Logging to Local Nonvolatile Storage (ATA Disk) feature can be enabled with the logging
persistent command, you must enable the logging of messages to an internal buffer with the logging
buffered command. For additional information, refer to the Writing Logging Messages to an ATA Disk,
page 29, and to the Prerequisites for Logging to Local Nonvolatile Storage (ATA Disk), page 27.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
27
System Logging Messages
Restrictions for Logging to Local Nonvolatile Storage (ATA Disk)
Restrictions for Logging to Local Nonvolatile Storage (ATA
Disk)
Available ATA Disk Space Constrains the Size and Number of Stored Log Files
The amount of ATA disk space allocated to system logging messages constrains the number of logging
files that can be stored. When the allocation threshold is passed, the oldest log file in the directory is
deleted to make room for new system logging messages. To permanently store system logging messages,
you must archive them to an external device. For more information, refer to the Copying Logging
Messages to an External Disk, page 30.
Note
Logging to Local Nonvolatile Storage can use up to 2 GB of storage space.
Information About Logging to Local Nonvolatile Storage (ATA
Disk)
The Logging to Local Nonvolatile Storage (ATA Disk) feature adds a router’s ATA flash disk as a storage
destination for logging messages. When using this feature, be sure to understand the following concepts:
•
•
System Logging Messages, page 28
ATA Flash Disks, page 28
System Logging Messages
System logging messages include error and debug messages generated by application programming
interfaces (APIs) on the router. Typically, logging messages are stored in a router’s memory buffer; when
the buffer is full, older messages are overwritten by new messages. All logging messages are erased from
the memory buffer when the router reboots.
ATA Flash Disks
ATA flash disks are PC cards included with some Cisco routers, which are used to provide nonvolatile data
storage. The greater the capacity of the ATA flash disk, the more data, such as logging messages, it can
hold. Logging messages written to an ATA flash disk persist when the router reboots.
How to Configure Logging to Local Nonvolatile Storage (ATA
Disk)
•
•
Writing Logging Messages to an ATA Disk, page 29
Copying Logging Messages to an External Disk, page 30
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
28
Writing Logging Messages to an ATA Disk
How to Configure Logging to Local Nonvolatile Storage (ATA Disk)
Writing Logging Messages to an ATA Disk
Perform this task to enable the Logging to Local Nonvolatile Storage (ATA Disk) feature and write logging
messages to an ATA flash disk:
SUMMARY STEPS
1. enable
2. configure terminal
3. logging buffered [buffer-size | severity-level]
4. logging persistent [url {disk0:/directory | disk1:/directory}] [size filesystem-size] [filesize loggingfile-size] [batch batch-size]
DETAILED STEPS
Command or Action
Step 1 enable
Purpose
Enables privileged EXEC mode.
•
Enter your password if prompted.
Example:
Router> enable
Step 2 configure terminal
Enables global configuration mode.
Example:
Router# configure terminal
Step 3 logging buffered [buffer-size |
severity-level]
Enables system message logging to a local buffer and limits messages logged to the
buffer based on severity.
•
Example:
Router(config)# logging
buffered
•
The optional buffer-size argument specifies the size of the buffer from 4096 to
4294967295 bytes. The default size varies by platform.
The optional severity-level argument limits the logging of messages to the buffer
to those no less severe than the specified level.
Step 4 logging persistent [url {disk0:/
Writes logging messages from the memory buffer to the specified directory on the
directory | disk1:/directory}] [size router’s ATA disk.
filesystem-size] [filesize logging• Before logging messages are written to a file on the ATA disk, the Cisco IOS
file-size] [batch batch-size]
software checks to see if there is sufficient disk space. If not, the oldest file of
logging messages (by timestamp) is deleted, and the current file is saved.
• The filename format of log files is log_MM:DD:YYYY::hh:mm:ss (for example,
Example:
log_06:10:2008::07:42:14).
Router(config)# logging
persistent url disk0:/syslog
size 134217728 filesize
16384 batch 5098
For Release 12.4(20)T and later releases, the filename format is changed to
log_YYYYMMDD-hhmmss (for example, log_20080610-074214).
This feature supports only one log file per second due to its filename format, which
contains a timestamp suffix down to the seconds level.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
29
Copying Logging Messages to an External Disk
Configuration Examples for Logging to Local Nonvolatile Storage (ATA Disk)
Copying Logging Messages to an External Disk
Perform this task to copy logging messages from the ATA flash disk to an external disk.
SUMMARY STEPS
1. enable
2. copy source-url destination-url
DETAILED STEPS
Command or Action
Purpose
Step 1 enable
Enables privileged EXEC mode.
•
Enter your password if prompted.
Example:
Router> enable
Step 2 copy source-url destination-url
Copies the specified file or directory on the ATA flash
disk via FTP to the specified URL.
Example:
Router# copy disk0:/syslog ftp://myuser/
mypass@192.168.1.129/syslog
Configuration Examples for Logging to Local Nonvolatile
Storage (ATA Disk)
•
•
Writing Logging Messages to an ATA Disk Example, page 30
Copying Logging Messages to an External Disk Example, page 30
Writing Logging Messages to an ATA Disk Example
The following example shows how to write up to 134217728 bytes (128 MB) of logging messages to the
syslog directory of disk 0, specifying a file size of 16384 bytes:
Router(config)# logging buffered
Router(config)# logging persistent url disk0:/syslog size 134217728 filesize 16384
Copying Logging Messages to an External Disk Example
The following example shows how to copy logging messages from the router’s ATA flash disk to an
external disk:
Router# copy disk0:/syslog ftp://myuser/mypass@192.168.1.129/syslog
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
30
Logging to Local Nonvolatile Storage (ATA Disk)
Additional References
Additional References
The following sections provide references related to the Logging to Local Nonvolatile Storage (ATA Disk)
feature.
Related Documents
Related Topic
Document Title
copy command
Cisco IOS Configuration Fundamentals Command
Reference
Network Management commands (including
logging commands): complete command syntax,
defaults, command mode, command history, usage
guidelines, and examples
Cisco IOS Network Management Command
Reference
Standards
Standards
Title
No new or modified standards are supported by this -feature, and support for existing standards has not
been modified by this feature.
MIBs
MIBs
MIBs Link
No new or modified MIBs are supported by this
feature, and support for existing MIBs has not been
modified by this feature.
To locate and download MIBs for selected
platforms, Cisco IOS releases, and feature sets, use
Cisco MIB Locator found at the following URL:
http://www.cisco.com/go/mibs
RFCs
RFCs
Title
No new or modified RFCs are supported by this
feature, and support for existing RFCs has not been
modified by this feature.
--
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
31
Logging to Local Nonvolatile Storage (ATA Disk)
Feature Information for Logging to Local Nonvolatile Storage (ATA Disk)
Technical Assistance
Description
Link
The Cisco Support website provides extensive
http://www.cisco.com/techsupport
online resources, including documentation and tools
for troubleshooting and resolving technical issues
with Cisco products and technologies.
To receive security and technical information about
your products, you can subscribe to various
services, such as the Product Alert Tool (accessed
from Field Notices), the Cisco Technical Services
Newsletter, and Really Simple Syndication (RSS)
Feeds.
Access to most tools on the Cisco Support website
requires a Cisco.com user ID and password.
Feature Information for Logging to Local Nonvolatile Storage
(ATA Disk)
The following table provides release information about the feature or features described in this module.
This table lists only the software release that introduced support for a given feature in a given software
release train. Unless noted otherwise, subsequent releases of that software release train also support that
feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.
Table 3
Feature Information for Logging to Local Nonvolatile Storage (ATA Disk)
Feature Name
Releases
Feature Information
Logging to Local Nonvolatile
Storage (ATA Disk)
12.0(26)S 12.2(25)S 12.2(28)SB
12.2(33)SRB 12.4(15)T
12.2(33)SB 12.4(20)T
The Logging to Local
Nonvolatile Storage (ATA Disk)
feature enables system logging
messages to be saved on an
advanced technology attachment
(ATA) flash disk. Messages
saved on an ATA drive persist
after a router is rebooted.
The following commands were
introduced or modified: logging
persistent, logging buffered.
Cisco and the Cisco Logo are trademarks of Cisco Systems, Inc. and/or its affiliates in the U.S. and other
countries. A listing of Cisco's trademarks can be found at www.cisco.com/go/trademarks. Third party
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
32
Logging to Local Nonvolatile Storage (ATA Disk)
trademarks mentioned are the property of their respective owners. The use of the word partner does not
imply a partnership relationship between Cisco and any other company. (1005R)
Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be
actual addresses and phone numbers. Any examples, command display output, network topology diagrams,
and other figures included in the document are shown for illustrative purposes only. Any use of actual IP
addresses or phone numbers in illustrative content is unintentional and coincidental.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
33
Copying Logging Messages to an External Disk Example
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
34
Reliable Delivery and Filtering for Syslog
The Reliable Delivery and Filtering for Syslog feature allows a device to be customized for receipt of
syslog messages. This feature provides reliable and secure delivery for syslog messages using Blocks
Extensible Exchange Protocol (BEEP). Additionally, it allows multiple sessions to a single logging host,
independent of the underlying transport method, and provides a filtering mechanism called a message
discriminator.
This module describes the functions of the Reliable Delivery and Filtering for Syslog feature and how to
configure them in a network.
•
•
•
•
•
•
•
•
Finding Feature Information, page 35
Prerequisites for Reliable Delivery and Filtering for Syslog, page 35
Restrictions for Reliable Delivery and Filtering for Syslog, page 36
Information About Reliable Delivery and Filtering for Syslog, page 36
How to Configure Reliable Delivery and Filtering for Syslog, page 41
Configuration Examples for Reliable Delivery and Filtering for Syslog, page 47
Additional References, page 48
Feature Information for Reliable Delivery and Filtering for Syslog, page 49
Finding Feature Information
Your software release may not support all the features documented in this module. For the latest feature
information and caveats, see the release notes for your platform and software release. To find information
about the features documented in this module, and to see a list of the releases in which each feature is
supported, see the Feature Information Table at the end of this document.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.
Prerequisites for Reliable Delivery and Filtering for Syslog
•
•
•
•
Router level rate limit is set to meet business needs, network traffic requirements, or performance
requirements.
Each BEEP session must have an RFC 3195-compliant syslog-RAW exchange profile.
A Simple Authentication and Security Layer (SASL) profile specifying “DIGEST-MD5” for
provisioning services must be established when a crypto image is used.
Syslog servers must be compatible with BEEP.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
35
BEEP Transport Support
Restrictions for Reliable Delivery and Filtering for Syslog
•
Syslog server applications must be capable of handling multiple sessions to use the multiple session
capability of the Reliable Delivery and Filtering for Syslog feature.
Restrictions for Reliable Delivery and Filtering for Syslog
•
•
•
•
•
Only the syslog-RAW, SASL, and Transport Layer Security (TLS) profiles are supported.
Both ends of a syslog session must use the same transport method.
A message discriminator must be defined before it can be associated with a specific syslog session.
A syslog session can be associated with only one message discriminator.
Message delivery with User Datagram Protocol (UDP) will be faster than with either TCP or BEEP.
Information About Reliable Delivery and Filtering for Syslog
•
•
•
•
•
•
BEEP Transport Support, page 36
Syslog Message, page 37
Syslog Session, page 37
Message Discriminator, page 39
Rate Limiting, page 40
Benefits of Reliable Delivery and Filtering for Syslog, page 41
BEEP Transport Support
BEEP is a generic application protocol framework for connection-oriented, asynchronous interactions. It is
intended to provide the features that traditionally have been duplicated in various protocol
implementations. BEEP typically runs on top of TCP and allows the exchange of messages. Unlike HTTP
and similar protocols, either end of the connection can send a message at any time. BEEP also includes
facilities for encryption and authentication and is highly extensible.
BEEP as a transport protocol for syslog messages provides multiple channels. Each channel can be
configured for a separate session to the same host. BEEP provides reliable transport. Syslog messages sent
over a BEEP connection are guaranteed to be delivered in sequence.
With command-line interface (CLI) commands introduced in the Reliable Delivery and Filtering for Syslog
feature, you can configure a new BEEP session to have a maximum of eight channels.
The figure below shows a BEEP session with eight channels, allowing eight separate syslog sessions.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
36
Syslog Message
Information About Reliable Delivery and Filtering for Syslog
Channels are identified as 1, 3, 5, 7, 9, 11, 13, and 15. The number of available channels (eight) was
designed to correspond to the number of severity levels of classic RFC-3164 syslog messages (0 to 7).
Message discriminators can be used such that severity levels are mapped to BEEP channels. An intelligent
BEEP syslog server (depending upon the BEEP stack used) could use this mapping to prioritize messages
with higher severity (see RFC 3081, section 3.1.4). Unless associated with a message discriminator, all
syslog sessions (channels) receive all syslog messages.
Syslog Message
A syslog message has a sequence number that allows the host to use the number as an identifier for the
message as well as to detect whether there were any gaps in the messages that were received. Syslog
messages are numbered consecutively. The reliability of BEEP does not replace the need for sequence
numbers, which are required for the following reasons:
•
•
•
A sequence number provides an easy way to identify a syslog message. Independent of reliability
considerations, the sequence number serves as a message identifier.
A BEEP session may not be in place for the entire time that a device sending syslog messages is up.
Sequence numbers provide a way for management applications to assess whether messages were
missed between BEEP sessions.
BEEP is only one of several transports. Unreliable transports are also used and the syslog protocol
should not rely on a reliable transport always being provided.
The existing numbering scheme for syslog messages is limited with the extension of syslog to
accommodate advanced message discrimination features and multiple hosts. Message discrimination leads
to gaps in the sequence numbers, meaning that hosts lose the ability to detect whether they have missed a
message. If syslog messages are numbered consecutively on each session to avoid the gaps in sequence
numbers, it will not be possible to easily correlate which messages are the same and which ones are
different because the sequence number would no longer uniquely identify a message.
To separate identification from sequencing and reliability, the following changes to syslog messages were
made:
•
•
The sequence number is retained as an identifier for the message. Messages with a lower number
precede messages with a higher number, but they are not guaranteed to be consecutive.
An additional field is added in the body portion of a syslog message to help ensure sequencing. The
contents of this field contain a sequence number for a particular session. The same message
transmitted over different sessions may have a different sequence number.
Syslog Session
A syslog session is a logical link from the syslog agent on a router to the recipient of a syslog message. For
example, a syslog session can be established between a syslog agent and any of the following:
•
•
•
•
Router console
Router logging buffer
Router monitor
External syslog server
A syslog session runs over a transport connection between the syslog source and the syslog destination. A
transport connection can use any of the following protocols:
•
•
TCP
UDP (association to one remote address and port)
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
37
Reliable Delivery and Filtering for Syslog
Multiple Syslog Sessions
•
BEEP (channel within a BEEP session)
The figure below shows a mapping of syslog sessions and transport protocols between a router and a syslog
server using an Open Systems Interconnection (OSI) model.
Note
The figure below is best viewed using Internet Explorer.
The figure below shows multiple syslog sessions from a single syslog agent to different hosts using UDP,
TCP and BEEP.
•
Multiple Syslog Sessions, page 38
Multiple Syslog Sessions
A syslog session is independent of a transport connection. A Cisco router can support multiple syslog
sessions, each running over its own transport connection. Multiple syslog sessions cannot share the same
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
38
Message Discriminator
Multiple Syslog Sessions
transport connection, but multiple syslog sessions may terminate at the same remote host, each running
over its own transport connection. An example is a BEEP session in which multiple channels are used.
The figure below shows an end-to-end view of a syslog session. Note the three syslog sessions within a
single BEEP session.
The TCP and UDP protocols do not have multiplexed channels but the protocols do allow for using
multiple ports to establish multiple syslog sessions to the same syslog host. To enable the UDP and TCP
transport methods to have capability similar to BEEP’s multiple channel capability, the Reliable Delivery
and Filtering for Syslog feature allows multiple syslog sessions to be established via the UDP and TCP
transport methods to the same logging host. Multiple syslog sessions going over BEEP sessions is also
supported.
Message Discriminator
A message discriminator is a syslog processor. A message discriminator is associated with a syslog session
and binds that session to a transport connection.
Prior to message delivery, the message is subject to the message discriminator with a user-specified list of
criteria. After the first filtering criterion results in a message being blocked, the filtering check stops.
Note
The sequence of criteria in the CLI does not affect the sequence in which criteria is checked.
•
Following are filtering criteria. These criteria are checked in the order listed here:
◦
◦
◦
◦
Severity level or levels specified
Facility within the message body that matches a regular expression
Mnemonic that matches a regular expression
Part of the body of a message that matches a regular expression
A message discriminator offers the following capabilities:
•
Optional rate limiting--Specifying a transmission rate of messages per time interval that is not to be
exceeded. If the rate limit is exceeded, messages are either delayed or dropped, at the discretion of the
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
39
Rate Limiting
Multiple Syslog Sessions
•
device. The application of a rate limiter means that reliable delivery of syslog messages over that
syslog session is no longer guaranteed. The purpose of a rate limiter is to avoid potential “flooding” at
recipient syslog servers for applications that do not require guaranteed syslog delivery.
Correlating--Inspecting candidate event messages and possibly aggregating information across events,
creating a new event that contains the aggregated information. Correlating functions include:
◦
◦
◦
Elimination of duplicate messages by maintaining a message count and waiting a specific time
period between sending the first message of a certain type and sending the next message of that
type
Elimination of oscillating messages
Simple message correlation; for example, if one message is a symptom of a cause reported by
another message, one consolidated message is reported
A message discriminator can be associated with a specific destination and transport; that is, the filter can be
host dependent. For this reason, a message discriminator is attached to a syslog session, transport, or
channel, with possible device support for multiple sessions, transports, or channels, each of which can be
attached to a different discriminator.
The establishment of a message discriminator should be separate from the establishment of a syslog
session. A message discriminator should refer to the syslog session, transport, or channel to which it should
be attached. The reasons for the separation are the following:
•
•
Message discriminators can be managed separately from the connections, and refinements in the
capabilities available to set up message discriminators need not affect how syslog sessions are set up
and vice versa.
Multiple connections can be attached to the same message discriminator, allowing for various syslog
redundancy topologies.
When an explicit message discriminator is not associated with a syslog session, the generic message
discriminator from the router-wide global settings is used. You can create an “empty” message
discriminator without specifying attribute values (no rate limit and no filter configured).
Rate Limiting
The router-wide rate limiting capability in Cisco IOS syslog is preserved in the Reliable Delivery and
Filtering for Syslog feature and is referred to as “global rate limiting.” If you do not use global rate
limiting, all event messages are sent to remote syslog hosts if system resources can support the volume.
When global rate limiting is set, it applies to all destinations. The value is set to the rate-limit attribute of
the “generic message discriminator” if one has been set. The disadvantage of global rate limiting is that the
rate limit of the least performing remote syslog host sets the rate for how fast a router can send out syslog
messages.
The Reliable Delivery and Filtering for Syslog feature provides syslog session-based rate limiting to bypass
the effects of global rate limiting. This session-based rate limiting is associated with a specific message
discriminator and allows you to set the rate acceptance level independently for each syslog session.
Use of global rate limiting is not recommended when session-based rate limiting is in effect. A rate limit in
a message discriminator specifies a not-to-exceed rate of syslog messages but does not guarantee that this
rate will be reached. A configured global rate limit may cause messages on a session to be dropped even if
the rate limit for that session has not been reached. These actions are important to understand if global rate
limiting and session-based rate limiting are used concurrently.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
40
Benefits of Reliable Delivery and Filtering for Syslog
How to Configure Reliable Delivery and Filtering for Syslog
Benefits of Reliable Delivery and Filtering for Syslog
•
•
•
•
•
•
Authentication and encryption capabilities in BEEP provide reliable and secure delivery for syslog
messages
Multiple sessions to a single logging host independent of the underlying transport method
Session-based message filtering and rate limiting
Multiple connections can be attached to the same message discriminator, allowing various syslog
redundancy topologies
New CLI command to disable the default syslog count
New CLI command to help identify relative positions of syslog messages that are dropped due to rate
limiting
How to Configure Reliable Delivery and Filtering for Syslog
•
•
•
•
•
•
Creating a Message Discriminator, page 41
Associating a Message Discriminator with a Logging Buffer, page 42
Associating a Message Discriminator with a Console Terminal, page 43
Associating a Message Discriminator with Terminal Lines, page 44
Enabling Message Counters, page 45
Adding and Removing a BEEP Session, page 46
Creating a Message Discriminator
Perform this task to create a message discriminator for syslog messages.
SUMMARY STEPS
1. enable
2. configure terminal
3. logging discriminator discr-name [[facility] [mnemonics] [msg-body] {drops string| includes
string}] [severity {drops sev-num | includes sev-num}] [rate-limit msglimit]
4. end
DETAILED STEPS
Command or Action
Step 1 enable
Purpose
Enables privileged EXEC mode.
•
Enter your password if prompted.
Example:
Router> enable
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
41
Associating a Message Discriminator with a Logging Buffer
How to Configure Reliable Delivery and Filtering for Syslog
Command or Action
Step 2 configure terminal
Purpose
Enters global configuration mode.
Example:
Router# configure terminal
Step 3 logging discriminator discr-name [[facility] [mnemonics] [msg- Creates a message discriminator with a facility
body] {drops string| includes string}] [severity {drops sev-num | subfilter.
includes sev-num}] [rate-limit msglimit]
In this example, all messages with “facl357” in the
facility field will be delivered.
Example:
Router(config)# logging discriminator pacfltr1 facility
includes facl357
Step 4 end
Returns the CLI to privileged EXEC mode.
Example:
Router(config)# end
Associating a Message Discriminator with a Logging Buffer
Perform this task to associate a message discriminator with a specific buffer.
SUMMARY STEPS
1. enable
2. configure terminal
3. logging discriminator discr-name [[facility] [mnemonics] [msg-body] {drops string| includes
string}] [severity {drops sev-num | includes sev-num}] [rate-limit msglimit]
4. logging buffered [discriminator discr-name | xml] [buffer-size] [severity-level]
5. end
DETAILED STEPS
Command or Action
Step 1 enable
Purpose
Enables privileged EXEC mode.
•
Example:
Router> enable
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
42
Enter your password if prompted.
Associating a Message Discriminator with a Console Terminal
How to Configure Reliable Delivery and Filtering for Syslog
Command or Action
Purpose
Step 2 configure terminal
Enters global configuration mode.
Example:
Router# configure terminal
Step 3 logging discriminator discr-name [[facility] [mnemonics] [msg-body]
{drops string| includes string}] [severity {drops sev-num | includes sevnum}] [rate-limit msglimit]
Creates a message discriminator.
Example:
Router(config)# logging discriminator pacfltr2
Step 4 logging buffered [discriminator discr-name | xml] [buffer-size] [severitylevel]
Enables logging to a local buffer and
specifies a message discriminator.
Example:
Router(config)# logging buffered discriminator pacfltr2 5
Step 5 end
Returns the CLI to privileged EXEC mode.
Example:
Router(config)# end
Associating a Message Discriminator with a Console Terminal
Perform this task to associate a message discriminator with a console terminal.
SUMMARY STEPS
1. enable
2. configure terminal
3. logging discriminator discr-name [[facility] [mnemonics] [msg-body] {drops string| includes
string}] [severity {drops sev-num | includes sev-num}] [rate-limit msglimit]
4. logging console [discriminator discr-name | xml] [severity-level]
5. end
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
43
Associating a Message Discriminator with Terminal Lines
How to Configure Reliable Delivery and Filtering for Syslog
DETAILED STEPS
Command or Action
Step 1 enable
Purpose
Enables privileged EXEC mode.
•
Enter your password if prompted.
Example:
Router> enable
Step 2 configure terminal
Enters global configuration mode.
Example:
Router# configure terminal
Step 3 logging discriminator discr-name [[facility] [mnemonics] [msg-body] Creates a message discriminator.
{drops string| includes string}] [severity {drops sev-num | includes
sev-num}] [rate-limit msglimit]
Example:
Router(config)# logging discriminator pacfltr3
Step 4 logging console [discriminator discr-name | xml] [severity-level]
Enables logging to the console and specifies a
message discriminator filtering messages at a
specific severity level.
Example:
Router(config)# logging console discriminator pacfltr3 1
Step 5 end
Returns the CLI to privileged EXEC mode.
Example:
Router(config)# end
Associating a Message Discriminator with Terminal Lines
Perform this task to associate a message discriminator with terminal lines and have messages display at a
monitor.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
44
Enabling Message Counters
How to Configure Reliable Delivery and Filtering for Syslog
SUMMARY STEPS
1. enable
2. configure terminal
3. logging discriminator discr-name [[facility] [mnemonics] [msg-body] {drops string| includes
string}] [severity {drops sev-num | includes sev-num}] [rate-limit msglimit]
4. logging monitor [discriminator discr-name| xml] [severity-level]
5. end
DETAILED STEPS
Command or Action
Purpose
Step 1 enable
Enables privileged EXEC mode.
•
Enter your password if prompted.
Example:
Router> enable
Step 2 configure terminal
Enters global configuration mode.
Example:
Router# configure terminal
Step 3 logging discriminator discr-name [[facility] [mnemonics] [msgbody] {drops string| includes string}] [severity {drops sev-num |
includes sev-num}] [rate-limit msglimit]
Creates a message discriminator.
Example:
Router(config)# logging discriminator pacfltr4
Step 4 logging monitor [discriminator discr-name| xml] [severity-level]
Specifies a message discriminator named pacfltr4
and enables logging to the terminal lines of
messages at severity level 2 and lower.
Example:
Router(config)# logging monitor discriminator pacfltr4 2
Step 5 end
Returns the CLI to privileged EXEC mode.
Example:
Router(config)# end
Enabling Message Counters
Perform this task to enable logging of debug, log, or syslog messages.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
45
Adding and Removing a BEEP Session
How to Configure Reliable Delivery and Filtering for Syslog
SUMMARY STEPS
1.
2.
3.
4.
enable
configure terminal
logging message-counter {debug | log | syslog}
end
DETAILED STEPS
Step 1
Command or Action
Purpose
enable
Enables privileged EXEC mode.
•
Enter your password if prompted.
Example:
Router> enable
Step 2
configure terminal
Enters global configuration mode.
Example:
Router# configure terminal
Step 3
logging message-counter {debug | log | syslog}
Enables logging of syslog messages.
Example:
Router(config)# logging message-counter syslog
Step 4
Returns the CLI to privileged EXEC mode.
end
Example:
Router(config)# end
Adding and Removing a BEEP Session
Perform this task to add and remove a BEEP session.
SUMMARY STEPS
1. enable
2. configure terminal
3. logging host {{ip-address | hostname} [vrf vrf-name] | ipv6{ipv6-address | hostname}} [discriminator
discr-name | [[filtered [stream stream-id] | xml]] [transport {[beep [audit] [channel chnl-number]
[sasl profile-name] [tls cipher [cipher-num] trustpoint trustpt-name]]] | tcp[audit] | udp} [port portnum]] [sequence-num-session] [session-id{hostname | ipv4 | ipv6 | string custom-string}]
4. end
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
46
Configuring Transport and Logging Example
Configuration Examples for Reliable Delivery and Filtering for Syslog
DETAILED STEPS
Command or Action
Purpose
Step 1 enable
Enables privileged EXEC mode.
•
Enter your password if prompted.
Example:
Router> enable
Step 2 configure terminal
Enters global configuration mode.
Example:
Router# configure terminal
Step 3 logging host {{ip-address | hostname} [vrf vrf-name] | ipv6{ipv6-address |
hostname}} [discriminator discr-name | [[filtered [stream stream-id] | xml]]
[transport {[beep [audit] [channel chnl-number] [sasl profile-name] [tls
cipher [cipher-num] trustpoint trustpt-name]]] | tcp[audit] | udp} [port portnum]] [sequence-num-session] [session-id{hostname | ipv4 | ipv6 | string
custom-string}]
Identifies a logging host and specifies
the transport protocol, port, and channel
for logging messages.
Example:
Router(config)# logging host host3 transport beep port 600 channel
3
Step 4 end
Returns the CLI to privileged EXEC
mode.
Example:
Router(config)# end
Configuration Examples for Reliable Delivery and Filtering for
Syslog
•
Configuring Transport and Logging Example, page 47
Configuring Transport and Logging Example
Router(config)# show running-config | include logging
logging buffered xml
logging
logging
logging host 209.165.201.1 transport udp port 601
logging synchronous
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
47
Reliable Delivery and Filtering for Syslog
Additional References
Router(config)# logging host 209.165.201.1 transport beep port 600 channel 3
Router(config)# logging host 209.165.201.1 transport tcp port 602
Router(config)# show running-config | include logging
logging buffered xml
logging
logging
logging host 209.165.201.1 transport udp port 601
logging host 209.165.201.1 transport beep port 600 channel 3
logging host 209.165.201.1 transport tcp port 602
logging synchronous
Router(config)#
Additional References
The following sections provide references related to the Reliable Delivery and Filtering for Syslog feature.
Related Documents
Related Topic
Document Title
Syslog logging
Troubleshooting and Fault Management module
Network Management commands (including
logging commands): complete command syntax,
defaults, command mode, command history, usage
guidelines, and examples
Cisco IOS Network Management Command
Reference
Standards
Standard
Title
No new or modified standards are supported by this -feature, and support for existing standards has not
been modified by this feature.
MIBs
MIB
MIBs Link
No new or modified MIBs are supported by this
feature, and support for existing MIBs has not been
modified by this feature.
To locate and download MIBs for selected
platforms, Cisco IOS releases, and feature sets, use
Cisco MIB Locator found at the following URL:
http://www.cisco.com/go/mibs
RFCs
RFC
Title
RFC 3195
Reliable Delivery for Syslog
RFC 3081, section 3.1.4
Mapping the BEEP Core onto TCP, “Use of Flow
Control”
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
48
Reliable Delivery and Filtering for Syslog
Feature Information for Reliable Delivery and Filtering for Syslog
RFC
Title
RFC 3164
The BSD Syslog Protocol
Technical Assistance
Description
Link
The Cisco Support website provides extensive
http://www.cisco.com/techsupport
online resources, including documentation and tools
for troubleshooting and resolving technical issues
with Cisco products and technologies.
To receive security and technical information about
your products, you can subscribe to various
services, such as the Product Alert Tool (accessed
from Field Notices), the Cisco Technical Services
Newsletter, and Really Simple Syndication (RSS)
Feeds.
Access to most tools on the Cisco Support website
requires a Cisco.com user ID and password.
Feature Information for Reliable Delivery and Filtering for
Syslog
The following table provides release information about the feature or features described in this module.
This table lists only the software release that introduced support for a given feature in a given software
release train. Unless noted otherwise, subsequent releases of that software release train also support that
feature.
Use Cisco Feature Navigator to find information about platform support and Cisco software image support.
To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
49
Reliable Delivery and Filtering for Syslog
Table 4
Feature Information for Reliable Delivery and Filtering for Syslog
Feature Name
Releases
Feature Information
Reliable Delivery and Filtering
for Syslog
12.4(11)T 12.2(33)SRB
12.2(33)SB Cisco IOS XE
Release 2.1 12.2(33)SXI
The Reliable Delivery and
Filtering for Syslog feature
allows a device to be customized
for receipt of syslog messages.
This feature provides for reliable
and secure delivery for syslog
messages using BEEP.
Additionally it allows multiple
sessions to a single logging host,
independent of the underlying
transport method, and provides a
filtering mechanism called a
message discriminator.
In Cisco IOS XE Release 2.1, this
feature was introduced on Cisco
ASR 1000 Series Routers.
The following commands were
introduced or modified: logging
buffered, logging console,
logging discriminator, logging
host, logging message-counter,
logging monitor, show logging.
Cisco and the Cisco Logo are trademarks of Cisco Systems, Inc. and/or its affiliates in the U.S. and other
countries. A listing of Cisco's trademarks can be found at www.cisco.com/go/trademarks. Third party
trademarks mentioned are the property of their respective owners. The use of the word partner does not
imply a partnership relationship between Cisco and any other company. (1005R)
Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be
actual addresses and phone numbers. Any examples, command display output, network topology diagrams,
and other figures included in the document are shown for illustrative purposes only. Any use of actual IP
addresses or phone numbers in illustrative content is unintentional and coincidental.
Embedded Syslog Manager Configuration Guide, Cisco IOS Release 12.4T
50
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising