Last Updated: July 2008.
Q. What is Service Diagnostics?
A. Service Diagnostics is a programmable diagnostics service that leverages other Cisco IOS Software capabilities-Embedded Event Manager (EEM), Embedded Syslog Manager (ESM) and Tool Command Language (Tcl). This feature is meant to be the "glue" that combines one or more of these tools to automate common diagnostic scenarios. The goal is to isolate the end user from the rigors of Tcl scripting, and/or EEM policy writing and provide a simple interface for deploying and receiving diagnostic information from scenario-specific troubleshooting scripts.
Q. How is Service Diagnostics different from Embedded Event Manager (EEM)?
A. EEM provides a programmable infrastructure that you need to write rules for. Service Diagnostics provides a set of ready-to-run rules on top of existing programmable infrastructure that includes EEM. Cisco IOS Service Diagnostics leverages EEM very heavily and provides framework and scripts focused on diagnostics. At a high level, this feature provides facilities to monitor system resources and isolate network neighborhood/protocol issues without having to know the CLI or SNMP MIBS or Tcl scripting.
Q. Does the Service Diagnostics feature need to run continuously in the background, or does it help users with troubleshooting activities?
A. This feature performs both activities. Diagnostics on demand is invoked upon request by a user to support troubleshooting and helps to identify a root cause of a problem quickly. Ongoing diagnostics are scripts that are continuously running to automatically provide additional information to resolve faults as soon as they occur.
Q. What areas of diagnostics are these scripts addressing?
A. We have posted four script-packages to diagnose common problem scenarios for BGP, OSPF, QoS and Resource Monitoring. The user will be allowed to configure inputs for various parameters and actions to be executed when there are network neighborhood problems.
Q. What are the different ways to run the scripts?
A. Proactive scripts run at a configurable interval. Reactive scripts run when an event in the network triggers them. The scripts need to be registered first before they can run. Each category for example BGP, OSPF, QoS or ERM, has a helper script that registers EEM policies and configures the EEM environment. These helper scripts are launched via the device's tclsh mode CLI. Optionally, if your image has the new Embedded Menu Manager (EMM) feature, a Menu Definition File (MDF) can be downloaded and run in lieu of the ZIP file.
Q. Are these scripts supported by Cisco?
A. No. Cisco is releasing these scripts to the community `as-is'. This is fairly typical with programming-other companies with a scripting interface often publish sample scripts. Of course, the underlying features (EEM, BGP, QoS, ERM etc.) are supported.
Q. Are the scripts digitally signed?
A. The diagnostic helper scripts are digitally signed. This is to authenticate that the scripts originate from Cisco and are not corrupted.
Q. Can I modify the scripts to custom-tailor them to my environment as needed?
A. Yes, absolutely.
Q. Can I share the scripts if I have made any modifications?
A. Yes, absolutely. We have a site called Cisco Beyond which can be found at http://www.cisco.com/go/ciscobeyond. Anyone can post scripts to this EEM development community site.
Q. Can I digitally sign the scripts that I write?
A. Yes. Please see the Cisco document `Signed Tcl Scripts' at http://www.cisco.com/en/US/products/ps6441/products_feature_guide09186a00808d65fe.html for guidance.
Q. What version of the Cisco IOS image do I need to have on my Cisco devices?
A. Your IOS image must support EEM 2.0 or later. EEM 2.0 is supported in Cisco IOS Release 12.2(25)S and later releases. EEM 2.1 is supported in Cisco IOS Release 12.3(14)T, 12.2(18)SXF5, 12.2(28)SB, 12.2(33)SRA, and later releases. Using MDF's requires the new EMM feature-which is in Release 12.4(20)T and later.
Q. What kind of development environment should I use to develop and test out my scripts?
A. Any source code editor would be good to develop Tcl scripts. You can test the scripts that you have written or modified by using the Tcl shell installed in a router or switch.
Q. Does the running of service diagnostics scripts modify my router configuration?
A. No, none of the scripts modify your network configuration. There will be no configuration changes related to BGP, OSPF, QoS or ERM after running the corresponding scripts/policies. The only configuration changes after running the service diagnostic scripts are the EEM environment variables in router configuration. EEM policy registration and environment configuration changes are required to deploy diagnostic scenarios.
Q. How much do these scripts cost to use?
A. No charge. The scripts are free.
Q. How do I deploy Service Diagnostics in my network?
A. You can deploy service diagnostics scripts like you would deploy Tcl scripts or EEM policies. There are both tclsh-based helper scripts (packaged in ZIP files) and Menu Definition Files (MDF) for use with EMM. Please see the Service Diagnostics User Guide for details.
Q. What is the performance impact of the scripts? Do you have any benchmark numbers?
A. There is no visible degradation of router performance in terms of CPU usage with all the scripts deployed on the router. This is with the timer values for EEM policies set to 120 seconds, which is the default value.
Q. What platforms are supported?
A. All platforms that run the Cisco IOS Software versions listed above. The tests were done extensively on the Cisco 7200 platform. Limited testing was done using the Cisco 3845 platform.
Q. How do the scripts notify me of the results after they run?
A. When you register the scripts, you can configure them to notify the diagnostic results via email or syslog messages.
Q. Can I change the output email format?
A. Yes. The email script uses environment variables for source and destination email. And you can reorder the sequence of commands. You can also add additional variables, for example, for customer ID or event ID.
Q. What ports do I need to open on the firewall?
A. The email is sent on port 25 using standard SMTP. Please be aware that email is sent using the IP address of the interface closest to the destination email server. Confirm that there is both a route and an Access Control List (ACL) to allow this to happen.
Q. How many scripts can be run on a device?
A. Service diagnostic scripts include tclsh scripts and EEM policy scripts. For tclsh service diagnostic scripts, there is no limitation on the number of scripts to be run. For EEM policy scripts, there is no limitation on the number of scripts that can be registered.
Q. How much time does a script take to run?
A. The time it takes to run a script depends on the length and complexity of the script. For example, the BGP route script takes approximately 1-2 seconds to run.
Q. Are there any script management utilities?
A. There are no script management utilities at this time; Cisco will be introducing Embedded Menu Manager (EMM) soon which will ease the task of deploying scripts and provides guidance to the end user through step-by-step configuration.
Q. What priority do the scripts run at?
A. Scripts run at MEDIUM priority. Cisco IOS command runs from a script run at the same priority.
Q. Do I need to have working knowledge of Tcl?
A. No, Tcl knowledge is not required to run service diagnostics as-is. Tcl scripting knowledge is required only for customizing scripts.
Q. Is there a user's guide available?
A. Yes, the user's guide is available on the Cisco IOS Service Diagnostics page on Cisco.com in the Product Literature section.
Q. How do I know if a script is signed or not?
A. At the start of the script, if you find a comment block beginning with #Cisco Tcl Signature V1.0, this indicates the script is signed.
Q. What if the IOS image on the device does not support signing of scripts? Will my scripts run?
A. Yes, even if the IOS image on the device does not support signing, the scripts can run. Signatures are Tcl comment blocks; and these will be ignored if the IOS image does not have the signing feature; they will be treated as standard Tcl comments.
Q. What is a Menu Definition File (MDF)?
A. The new Cisco IOS feature called Embedded Menu Manager (EMM) uses MDF's that define Menus/Submenus/Wizards in order to guide users through complex tasks. MDF's are XML documents containing embedded Tcl.
Q. How do I use a Menu Definition File (MDF)?
A. If your image has the new Cisco IOS feature called Embedded Menu Manager (EMM) , from privileged exec mode, simple run the following command:
Router# emm mdf disk0:/sdiag_bgp.mdf
MDF's can be located on local or remote storage (ie:flash:, tftp: server, etc.).