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.

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.

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 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 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 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.

• Event & 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.

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.

The Diagnostic Signature feature is enabled by default on the Cisco software. The following is the workflow for using diagnostic signatures:

1. 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.

2. The device downloads all assigned DS(es) or a specific DS by regular periodic download or by on-demand forced download.

3. 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.

4. The device continues sending periodic regular DS download requests to get the latest revision of DS and replace the older one in device.

5. The device monitors the event and executes the actions defined in the DS when the event happens.

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.

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.

Note	The predefined 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 http setting.

1.    enable


2.    configure terminal


3.    service call-home


4.    call-home


5.    contact-email-addr email-address


6.    mail-server {ipv4-addr | ipv6-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

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 10.1.1.1 priority 4

Device(cfg-call-home)# profile user1

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

Device(cfg-call-home-profile)# destination address http https://tools.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

Set the profile configured in the previous procedure as the DS profile and configure other DS parameters.

1.    call-home


2.    diagnostic-signature


3.    profile ds-profile-name


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


5.    end


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


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

Device(config)# call-home

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

Device# call-home diagnostic-signature download 6030

Device# show call-home diagnostic-signature actions