High Availability Configuration Guide, Cisco IOS Release 15S
Configuring Diagnostic Signatures
Downloads: This chapterpdf (PDF - 1.35 MB) The complete bookPDF (PDF - 3.21 MB) | The complete bookePub (ePub - 566.0 KB) | Feedback

Configuring Diagnostic Signatures

Configuring Diagnostic Signatures

The Diagnostic Signatures feature downloads digitally signed signatures to devices. Diagnostic Signatures (DS) files are formatted files that collate knowledge of diagnostic events and provide methods to troubleshoot them without a need to upgrade the Cisco software. The aim of DS is to deliver flexible intelligence that can detect and collect troubleshooting information that can be used to resolve known problems in customer networks.

Finding Feature Information

Your software release may not support all the features documented in this module. For the latest caveats and feature information, see Bug Search Tool and 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 module.

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 Diagnostic Signatures

Before you download and configure diagnostic signatures (DS) on a device, you must ensure that the following conditions are met:

Information About Diagnostic Signatures

Diagnostic Signatures Overview

Diagnostic signatures (DS) subsystem is introduced within the call-home system to provide a flexible framework that allows the defining of new events and corresponding CLIs that can analyze these events without upgrading the Cisco software.

DS provides you the ability to define more types of events and trigger types to perform the required actions than the Call-Home feature. The DS subsystem downloads and processes files on a device as well as handles callbacks for diagnostic signature events.

The Diagnostic signature feature downloads digitally signed signatures that are in the form of files to devices. DS files are formatted files that collate the knowledge of diagnostic events and provide methods to troubleshoot these events.

DS files contain XML data to specify the event description, and these files include a CLI to perform required actions. These files are digitally signed by Cisco or a third party to certify its integrity, reliability, and security.

The structure of a DS file can be one of the following formats:

  • Metadata-based simple signature that specifies event type and contains other information that can be used to match the event, perform actions such as collecting information by using the CLI or resetting the line card in the device if there is an event match.

  • Embedded Event Manager (EEM) Tool Command Language (Tcl) script-based signature that specifies new events in the event register line and additional action in the Tcl script.

  • Combination of both the formats mentioned above.

The following basic information is contained in a DS file:

  • ID (unique string)—unique key that represents a DS file that can be used to search a DS.

  • Name (ShortDescription)—unique description of the DS file that can be used in lists for selection.

  • Description—long description about the signature.

  • Revision—version number, which increments when the DS content is updated.

  • ProductFamily

    • OsVersion (multiple values)—a list of operating system versions for each product family.

    • Technology—technology that the DS belongs to.

Diagnostic Signature Downloading

To download the diagnostic signature (DS) file, you require the secure HTTP (HTTPS) protocol. If you have already configured an email transport method to download files on your device, you must change your assigned profile transport method to HTTPS to download and use DS.

Cisco software uses a PKI Trustpool Management feature, which is enabled by default on devices, to create a scheme to provision, store, and manage a pool of certificates from known certification authorities (CAs). The trustpool feature installs the CA certificate automatically. The CA certificate is required for the authentication of the destination HTTPS servers. Therefore, to enable the HTTPS protocol, the firewall is bypassed to access the service call-home (SCH) HTTPS server. The target URLs, which are defined in the SCH HTTPS server, must be one of the Technical Assistance Center (TAC) HTTPS URLs: .

There are two types of DS update requests to download DS files: regular and forced-download.

Regular download requests DS files that were recently updated. You can trigger a regular download request either by using a periodic configuration or by initiating an on-demand CLI. The regular download update happens only when the version of the requested DS is different from the version of the DS on the device. Periodic download is enabled by checking responses to periodic inventory messages. When an inventory message checks for any assigned DS on the device, the device sends a DS update request message that requests for an updated DS. In a DS update request message, the status and revision number of the DS is included such that only a DS with the latest revision number is downloaded.

Forced-download downloads a specific DS or a set of DSes. You can trigger the forced-download update request only by initiating an on-demand CLI. In a force-download update request, the latest version of the DS file is downloaded irrespective of the current DS file version on the device.

Diagnostic Signature Signing

The diagnostic signature (DS) files are digitally signed before they are made available for downloading. The following methods are used for digitally signing DS files:

  • Signing algorithm (Rivest Shamir and Adleman [RSA] 2048 bits)

  • Request keypairs to Abraxas system, which is the digital signing client

  • DS signed via secure socket layer (SSL) through a code signing client, where the signature is embedded using XML tags

  • Public keys are embedded in the DS subsystem (Cisco signed, partner signed, third-party signed) in the Cisco software. The digitally signed DS file contains the product name such as Diagnostic_Signatures (Cisco signed), Diagnostic_Signatures_Partner, Diagnostic_Signatures_3rd_Party. The product names are only used to sign the DS files.

The digital signing client can be found at https:/​/​abraxas.cisco.com/​SignEngine/​submit.jsp

These conditions that must be met to verify the digital signature in a DS file:

  • Code sign component support must be available in Cisco software.

  • Various public keys that verify the different kinds of diagnostic signatures must be included in platforms where DS is supported.

  • After parsing and retrieving the DS, the DS must execute the verification application program interface (API) to verify that the DS is valid.

Diagnostic Signature Workflow

The Diagnostic Signature is enabled by default on the Cisco software.

  • Use the destination transport-method http command to configure both email and HTTP data transfer methods to download DSes.

  • Download all DS files or specific DS files either by using the on-demand or periodic download.

  • Store the downloaded DS files on nonremovable disks, such as bootflash or harddisk, so that DS files can be read after a device reload. Syslog messages are displayed if the disk space is not sufficient.

  • Use periodic download to verify if the same version of DS is already available on the device. If a different version of DS is available on the device, the older version is uninstalled and the newer version is installed. Service disruption may occur during this time because of the unavailability of the DS.

  • Associate the DS on your device with only one profile. Associating a DS with two different profiles may lead to unexpected results.

  • Use the severity and pattern of occurrence of events on the device to determine the CLI commands that must be included in the new DS to trigger actions. For events that have already been identified, the metadata of the DS is in a much simpler format.

The DS metadata is parsed and stored in a database for event registration and information collection. When an event occurs, the action specified in the DS is performed.

Diagnostic Signature Events and Actions

Diagnostic signature (DS) events and actions are defined while digitally signing a DS. The DS events and actions data are included after the administrator metadata and operational metadata in the DS.

Diagnostic Signature Event Detection

Event detection in DS is defined in two ways: single event detection and multiple event detection.

Single Event Detection

In single event detection, only one event detector is defined within a DS. The event specification format is one of the following two types:

  • DS event specification type—syslog, environment, diagnostic, periodic, configuration, Online Insertion Removal (OIR), immediate, and call-home are the supported event types, where “immediate” indicates that these types of DSes do not contain any event detection part and “call-home” type modifies the existing CLI commands. After the registration of the event types, the DS performs the associated action immediately.

  • Embedded Event Manager (EEM) specification type—supports all existing EEM event types. The EEM specification type also supports a new EEM event detector without having to modify the Cisco software.

Other than using EEM to detect events, DS is triggered when a Tool Command Language (Tcl) script is used to specify event detection types.

Multiple Event Detection

Multiple event detection involves defining two or more event detectors, two or more corresponding tracked object states, and a time period for the events to occur. The specification format for multiple event detection can include complex event correlation for tracked event detectors. For example, three event detectors—syslog, OIR, and IPSLA—are defined during the creation of a DS file. The correlation that is specified for these event detectors is that the DS will execute its action if both syslog and OIR events are triggered simultaneously, or if IPSLA is triggered alone.

Diagnostic Signature Actions and Variables

The diagnostic signature (DS) files consists of various actions that must be initiated when an event occurs. The action type indicates the kind of action that will be initiated in response to a certain event.

Variables are elements within a DS file that are used to customize the files.

Action Types

DS actions are categorized into the following four types:

  • Call-home

  • Command

  • Emailto

  • Script

DS action types call-home and emailto collect event data and send a message to call-home servers or to the defined email addresses. The message includes the following elements:

  • Message type—diagnostic-signature

  • Message subtype—ds-id

  • Message description—event-id : ds name

The commands defined for the DS action type initiates CLI commands that can change configuration of the device. The DS action type script executes Tcl scripts.


Variables are referenced within a DS and are used to customize the DS file. All DS variable names have the prefix ds_ to separate them from other variables. In some situations, DS runs a set of commands simultaneously based on the last command result or a set of commands based on the variables defined within a DS. The following are the supported DS variable types:

  • System variable—values assigned automatically by the device without any configuration changes. The Diagnostic Signatures feature supports two types of system variables: ds_hostname and ds_signature_id.

  • Environment variable—values assigned manually by using the environment variable-name variable-value command in call-home diagnostic-signature configuration mode. Use the show call-home diagnostic-signature command to display the name and value of all DS environment variables.

  • Prompt variable—values assigned manually by using the call-home diagnostic-signature install ds-id command in privileged EXEC mode. If you do not set this value, the status of the DS indicates pending.

  • Regular expression variable—values assigned from a regular expression pattern match with predefined CLI command outputs.

  • Syslog event variable—values assigned during an event detection in the DS file. This variable is valid only for syslog event detection.

How to Configure Diagnostic Signatures

Configuring Service Call-Home for Diagnostic Signatures

Configure the service call-home feature to set attributes such as the contact email address where notifications regarding diagnostic signature (DS) downloads are sent and destination HTTP/secure HTTP (HTTPS) URL to download the DS files from. These attributes are set for the call-home profile user1. For periodic downloads, schedule the time when the diagnostic signature files must be downloaded.


    1.    enable

    2.    configure terminal

    3.    service call-home

    4.    call-home

    5.    contact-email-addr email-address

    6.    mail-server {ipv4-addr | name} priority number

    7.    profile profile-name

    8.    destination transport-method {email | http}

    9.    destination address {email address | http url}

    10.    subscribe-to-alert-group inventory [periodic {daily hh:mm | monthly day hh:mm | weekly day hh:mm}]

    11.    exit

     Command or ActionPurpose
    Step 1 enable


    Device> enable

    Enables privileged EXEC mode.

    • Enter your password if prompted.

    Step 2configure terminal


    Device# configure terminal

    Enters global configuration mode.

    Step 3 service call-home


    Device(config)# service call-home

    Enables call-home service on a device.

    Step 4 call-home


    Device(config)# call-home

    Enters call-home configuration mode for the configuration of call-home settings.

    Step 5 contact-email-addr email-address


    Device(cfg-call-home)# contact-email-addr userid@example.com

    (Optional) Assigns an email address to be used for call-home customer contact.

    Step 6mail-server {ipv4-addr | name} priority number


    Device(cfg-call-home)# mail-server priority 4

    Configures a Simple Mail Transfer Protocol (SMTP) email server address for call-home.

    Step 7profile profile-name


    Device(cfg-call-home)# profile user1

    Configures a destination profile for call-home and enters call-home profile configuration mode.

    Step 8 destination transport-method {email | http}


    Device(cfg-call-home-profile)# destination transport-method http

    Specifies a transport method for a destination profile in the call-home.

    Step 9 destination address {email address | http url}


    Device(cfg-call-home-profile)# destination address http https://tools-stage.cisco.com/its/service/oddce/services/DDCEService

    Configures the address type and location to which call-home messages are sent.

    Step 10subscribe-to-alert-group inventory [periodic {daily hh:mm | monthly day hh:mm | weekly day hh:mm}]


    Device(cfg-call-home-profile)# subscribe-to-alert-group inventory periodic daily 14:30

    Configures a destination profile to receive messages for the Inventory alert group for call-home.

    • This command is used only for the periodic downloading of DS files.

    Step 11exit


    Device(cfg-call-home-profile)# exit

    Exits call-home profile configuration mode and returns to call-home configuration mode.

    What to Do Next

    Configure DS with profile user1 as described in the “Configuring Diagnostic Signatures” section. The attributes set for the call-home profile user1 apply to DS.

    Configuring Diagnostic Signatures

    Before You Begin

    Configure the Service Call-Home feature to set attributes for the call-home profile user1 as described in the “Configuring Service Call-Home for Diagnostic Signatures” section. When you configure diagnostic signatures (DSes), define the same profile name user1. DS then uses the attributes set for user1.


      1.    diagnostic-signature

      2.    profile ds-profile-name

      3.    environment ds_ env-varname ds-env-varvalue

      4.    end

      5.    call-home diagnostic-signature {{deinstall | download} {ds-id | all} | install ds-id}

      6.    show call-home diagnostic-signature [ds-id [actions | events | prerequisite | prompt | variables] | failure | statistics [download]]

      7.    debug call-home diagnostic-signature {action | all | api | cli | download | event-registration | parsing}

       Command or ActionPurpose
      Step 1diagnostic-signature


      Device(cfg-call-home)# diagnostic-signature

      Enters call-home diagnostic signature mode.

      Step 2profile ds-profile-name


      Device(cfg-call-home-diag-sign)# profile user1

      Specifies the destination profile on a device that DS uses.

      Step 3environment ds_ env-varname ds-env-varvalue


      Device(cfg-call-home-diag-sign)# environment ds_env1 envarval

      Sets the environment variable value for DS on a device.

      Step 4end


      Device(cfg-call-home-diag-sign)# end

      Exits call-home diagnostic signature mode and returns to privileged EXEC mode.

      Step 5call-home diagnostic-signature {{deinstall | download} {ds-id | all} | install ds-id}


      Device# call-home diagnostic-signature download 6030

      Downloads, installs, and uninstalls diagnostic signature files on a device.

      Step 6show call-home diagnostic-signature [ds-id [actions | events | prerequisite | prompt | variables] | failure | statistics [download]]


      Device# show call-home diagnostic-signature

      Displays the attributes and statistics of a call-home diagnostic signature file on a device.

      Step 7debug call-home diagnostic-signature {action | all | api | cli | download | event-registration | parsing}


      Device# debug call-home diagnostic-signature all

      Displays debugging of one or all of the call-home diagnostic signature flags on a device.


      Configuration Examples for Diagnostic Signatures

      Examples: Configuring Diagnostic Signatures

      The following example shows how to enable the periodic downloading request for diagnostic signature (DS) files. This configuration will send download requests to the service call-home server daily at 2:30 p.m. to check for updated DS files. The transport method is set to HTTP.

      Device> enable
      Device# configure terminal
      Device(config)# service call-home
      Device(config)# call-home
      Device(cfg-call-home)# contact-email-addr userid@example.com
      Device(cfg-call-home)# mail-server priority 4
      Device(cfg-call-home)# profile user-1
      Device(cfg-call-home-profile)# destination transport-method http
      Device(cfg-call-home-profile)# destination address http https://tools-dev.cisco.com/its/service/oddce/services/DDCEService 
      Device(cfg-call-home-profile)# subscribe-to-alert-group inventory periodic daily 14:30
      Device(cfg-call-home-profile)# exit
      Device(cfg-call-home)# diagnostic-signature
      Device(cfg-call-home-diag-sign)# profile user1
      Device(cfg-call-home-diag-sign)# environment ds_env1 envarval 
      Device(cfg-call-home-diag-sign)# end

      The following is sample output from the show call-home diagnostic-signature command for the configuration displayed above:

      Device# show call-home diagnostic-signature
      Current diagnostic-signature settings:
      Diagnostic-signature: enabled
      Profile: user1 (status: ACTIVE)
      Environment variable:
      ds_env1: abc
      Downloaded DSes:
      DS ID    DS Name                         Revision Status     Last Update (GMT+00:00)
      -------- ------------------------------- -------- ---------- -------------------
      6015     CronInterval                    1.0      registered 2013-01-16 04:49:52
      6030     ActCH                           1.0      registered 2013-01-16 06:10:22
      6032     MultiEvents                     1.0      registered 2013-01-16 06:10:37
      6033     PureTCL                         1.0      registered 2013-01-16 06:11:48

      Additional References for Diagnostic Signatures

      Technical Assistance

      Description Link

      The Cisco Support website provides extensive 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 Configuring Diagnostic Signatures

      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 1 Feature Information for Configuring Diagnostic Signatures

      Feature Name


      Feature Information

      Diagnostic Signatures



      The Diagnostic Signatures feature downloads digitally signed signatures to devices. Diagnostic Signatures (DS) files are formatted files that collate knowledge of diagnostic events and provide methods to troubleshoot them without a need to upgrade the Cisco software. The aim of DS is to deliver flexible intelligence that can detect and collect troubleshooting information that can be used to resolve known problems in customer networks.

      The following commands were introduced or modified:

      active (diagnostic signature), call-home diagnostic-signature, clear call-home diagnostic-signature statistics, debug call-home diagnostic-signature, diagnostic-signature, environment (diagnostic signature), profile (diagnostic signature), and show call-home diagnostic-signature.