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 customers networks.
Prerequisites
for Diagnostic Signatures
Before you download
and configure diagnostic signatures (DSs) on a device, you must ensure that the
following conditions are met:
Diagnostic
Signatures Overview
Diagnostic
signatures (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.
DSs provide the
ability to define more types of events and trigger types 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.
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 CLI commands or
scripts to perform required actions. These files are digitally signed by Cisco
or a third party to certify their integrity, reliability, and security.
The structure of a
DS file can be one of the following formats:
-
Metadata-based
simple signature that specifies the 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.
-
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 above.
The following basic
information is contained in a DS file:
-
ID (unique
number): 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.
-
Event &
Action: defines the event to be detected and the action to be performed after
the event happens.
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.
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 only started after there is any DS assigned to the
device from DS web portal. After the assignment happens, the response to the
periodic inventory message from the same device will include a field to notify
device to start its periodic DS download/update. 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.
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.
Diagnostic
Signature Workflow
The diagnostic
signature feature is enabled by default in 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.
-
The device
downloads all assigned DS(es) or a specific DS by regular periodic download or
by on-demand forced download.
-
The device
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. On the Cisco
ASR 901 Series Routers, the DS file is stored in the flash:/directory.
-
The device
continues sending periodic regular DS download requests to get the latest
revision of DS and replace the older one in device.
-
The device
monitors the event and executes the actions defined in the DS when the event
happens.
Diagnostic
Signature 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 s how command outputs and sending them to Smart
Call Home to parse.
Diagnostic
Signature Event Detection
Event detection in a
DS is defined in two ways: single event detection and multiple 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, periodic, configuration, 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.
-
The Embedded
Event Manager (EEM) specification type: supports any new EEM event detector
without having to modify the Cisco software.
Other than using EEM
to detect events, a 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 ore 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 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 syslog or IPSLA are triggered.
Diagnostic
Signature Actions
The diagnostic
signature (DS) file 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
that are used to customize the files.
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 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.
Diagnostic
Signature Variables
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 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. 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.
-
Regular
expression 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.
Feedback