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.
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.
Use Cisco Feature
Navigator to find information about platform support and Cisco software image
support. To access Cisco Feature Navigator, go to
An account on Cisco.com is not required.
Before you download
and configure diagnostic signatures (DSes) on a device, you must ensure that
the following conditions are met:
You must assign
a DS to the device. Refer to the “Diagnostic Signature Downloading” section for
more information on how to assign DSes to devices.
(HTTPS) transport is required for downloading DS files. You must install the
certification authority (CA) certificate to enable the authentication of the
destination HTTPS server.
If you configure the trustpool feature, the CA certificate is not
(DS) for the call-home system provides a flexible framework that allows the
defining of new events and corresponding CLIs that can analyze these events
without upgrading the Cisco software.
DSes provides the
ability to define more types of events and trigger types to perform the
required actions than the standard Call Home feature supports. The DS subsystem
downloads and processes files on a device as well as handles callbacks for
diagnostic signature events.
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 CLI commands or
scripts 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:
simple signature that specifies event type and contains other information that
can be used to match the event and perform actions such as collecting
information by using the CLI . The signature can also change configurations on
the device as a workaround for certain bugs.
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.
both the formats mentioned above.
The following basic
information is contained in a DS file:
string): unique key that represents a DS file that can be used to search a DS.
(ShortDescription): unique description of the DS file that can be used in lists
description about the signature.
number, which increments when the DS content is updated.
Action: defines the event to be detected and the action to be performed after
the event happens.
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.
There are two types
of DS update requests to download DS files: regular and forced-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.
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.
The DS file is digitally signed, and signature verification is performed
on every downloaded DS file to make sure it is from a trusted source.
Signature feature is enabled by default on the Cisco software. The following is
the workflow for using diagnostic signatures:
Find the DS(es)
you want to download and assign them to the device. This step is mandatory for
regular periodic download, but not required for forced download.
downloads all assigned DS(es) or a specific DS by regular periodic download or
by on-demand forced download.
verifies the digital signature of every single DS. If verification passes, the
device stores the DS file into a non-removable disk, such as bootflash or hard
disk, so that DS files can be read after the device is reloaded.
continues sending periodic regular DS download requests to get the latest
revision of DS and replace the older one in device.
monitors the event and executes the actions defined in the DS when the event
Events and Actions
The events and actions
sections are the key areas used in diagnostic signatures. The event section
defines all event attributes that are used for event detection. The action
section lists all actions which should be performed after the event happens,
such as collecting
show command outputs and sending them to Smart
Call Home to parse.
In single event
detection, only one event detector is defined within a DS. The event
specification format is one of the following two types:
specification type: syslog, periodic, configuration, Online Insertion Removal
(OIR) immediate, and call-home are the supported event types, where "immediate"
indicates that this type of DS does not detect any events, its actions are
performed once it is downloaded, and the call-home type modifies the current
CLI commands defined for existing alert-group.
Manager (EEM) specification type: supports any 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.
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.
signature (DS) file consists of various actions that must be initiated when an
evnt 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.
DS actions are
categorized into the following five types:
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 uses
"diagnostic-signature" as its message type and DS ID as the message sub-type.
The commands defined
for the DS action type initiate CLI commands that can change configuration of
the device, collect show command outputs, or run any EXEC command on the
device. The DS action type script executes Tcl scripts.
DS action type message defines action to generate message to notify or
remind user certain important information. The message could be broadcasted to
all TTY lines or generated as a syslog entry.
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. The following are the supported DS variable types:
System variable: variables
assigned automatically by the device without any configuration changes. The
Diagnostic Signatures feature supports two system variables: ds_hostname and
values assigned manually by using the
environmentvariable-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. If the DS file
contains unresolved environment variables, this DS will stay in pending status
until the variable gets resolved.
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.
variable: values assigned from a regular expression pattern match with
predefined CLI command outputs. The value is assigned during the DS run.
Syslog event variable:
values assigned during a syslog event detection in the DS file. This variable
is valid only for syslog event detection.
Home Service for Diagnostic Signatures
Configure the call
home service 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.
You can also create a new user profile, configure correct attributes
and assign it as the DS profile. For periodic downloads, the request is sent
out just following full inventory message. By changing the inventory periodic
configuration, the DS periodic download also gets rescheduled.
CiscoTAC-1 profile is enabled as a DS profile by default and we recommend using
it. If used, you only need to change the destination transport-method to the
destination profile to receive messages for the Inventory alert group for
command is used only for the periodic downloading of DS files.
Call-Home profile configuration mode and returns to Call-Home configuration
What to Do Next
Set the profile
configured in the previous procedure as the DS profile and configure other DS
Before You Begin
Configure the Call
Home Service feature to set attributes for the Call Home profile as described
in the “Configuring Call Home Service for Diagnostic Signatures” section. You
can either use the default CiscoTAC-1 profile or use the newly-created user
Device# show call-home diagnostic-signature actions
call-home diagnostic signature information.
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.
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
Access to most tools on the Cisco Support website requires a
Cisco.com user ID and password.
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
An account on Cisco.com is not required.
Table 1 Feature Information for
Configuring Diagnostic Signatures
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.
commands were introduced or modified:
(diagnostic signature), and