The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
The Call Home feature is a notification system that
sends alerts for critical system events via email and web-based notifications,
supports various message formats for compatibility with pager, email, and automated XML parsing applications, and
enables direct paging of a network support engineer, e-mail notification to a Network Operations Center, XML delivery to a support website, or use of Cisco Smart Call Home services for direct case generation with the Cisco Systems Technical Assistance Center (TAC).
Your software release may not support all of the features documented in this module. For the latest feature information and caveats, see the release notes for your platform and software release.
Use the Cisco Feature Navigator to find information about platform support and Cisco IOS and Catalyst OS software image support. To access Cisco Feature Navigator, see http://tools.cisco.com/ITDIT/CFN/. A Cisco account is not required to access the Cisco Feature Navigator.
Before you configure Call Home, ensure that these conditions are met.
Configure the contact e-mail address (required for full registration with Smart Call Home, optional if Call Home is enabled in anonymous mode). Optionally, provide a phone number and street address information. This information enables the receiver to determine the origin of received messages.
At least one destination profile (predefined or user-defined) must be configured. Select the destination profile based on the type of receiving entity: pager, e-mail address, or an automated service such as Cisco Smart Call Home.
If the destination profile uses e-mail message delivery, you must specify a Simple Mail Transfer Protocol (SMTP) server.
The router must have IP connectivity to an e-mail server or the destination HTTP server.
If Cisco Smart Call Home is used, an active service contract covering the device is required to provide full Cisco Smart Call Home service.
The Call Home feature can deliver alert messages containing information on configuration, environmental conditions, inventory, syslog, snapshot, and crash events. It provides these alert messages as either e-mail-based or web-based messages. Multiple message formats are available, allowing for compatibility with pager services, standard e-mail, or XML-based automated parsing applications. This feature can deliver alerts to multiple recipients, referred to as Call Home destination profiles, each with configurable message formats and content categories. A predefined destination profile is provided for sending alerts to the Cisco TAC (callhome@cisco.com). You can also define your own destination profiles.
Flexible message delivery and format options make it easy to integrate specific support requirements.
The Call Home feature offers these benefits:
Multiple message-format options, which include:
Short Text—Suitable for pagers or printed reports.
Plain Text—Full formatted message information suitable for human reading.
XML—Machine-readable format using XML and Adaptive Markup Language (AML) document type definitions (DTDs). The XML format enables communication with the Cisco TAC.
Multiple concurrent message destinations.
Multiple message categories including configuration, environmental conditions, inventory, syslog, snapshot, and crash events.
Filtering of messages by severity and pattern matching.
Scheduling of periodic message sending.
If you have a service contract directly with Cisco, you can register for the Smart Call Home service. Smart Call Home analyzes Smart Call Home messages and provides background information and recommendations. For known issues, particularly online diagnostics failures, Automatic Service Requests are generated with the Cisco TAC.
Smart Call Home offers these features:
Continuous device health monitoring and real-time diagnostic alerts.
Analysis of Smart Call Home messages and, if needed, Automatic Service Request generation routed to the correct TAC team, including detailed diagnostic information to speed problem resolution.
Secure message transport directly from your device or through an HTTP proxy server or a downloadable Transport Gateway (TG). You can use a TG aggregation point to support multiple devices or in cases where security dictates that your devices may not be connected directly to the Internet.
Web-based access to Smart Call Home messages and recommendations, inventory, and configuration information for all Smart Call Home devices provides access to associated field notices, security advisories, and end-of-life information.
You need these items to register for Smart Call Home:
SMARTnet contract number for your router
Your e-mail address
Your Cisco.com username
For more information about Smart Call Home, see https://supportforums.cisco.com/community/4816/smart-call-home.
Smart Call Home is a service capability included with many Cisco service contracts and is designed to assist customers resolve problems more quickly. In addition, the information gained from crash messages helps Cisco understand equipment and issues occurring in the field. If you decide not to use Smart Call Home, you can still enable Anonymous Reporting to allow Cisco to securely receive minimal error and health information from the device. If you enable Anonymous Reporting, your customer identity will remain anonymous, and no identifying information will be sent.
 Note |
When you enable Anonymous Reporting, you acknowledge your consent to transfer the specified data to Cisco or to vendors operating on behalf of Cisco (including countries outside the United States). Cisco maintains the privacy of all customers. For information about how Cisco treats personal information, see the Cisco Privacy Statement at http://www.cisco.com/web/siteassets/legal/privacy.html. |
When Call Home is configured in an anonymous way, only crash, inventory, and test messages are sent to Cisco. No customer identifying information is sent.
For more information about what is sent in these messages, see Alert group trigger events and commands.
To configure Call Home using a single command:
Use these procedures for detailed or optional configurations:
To enable all Call Home basic configurations using a single command, perform the following steps:
|
Step 1 |
configure terminal Example:Enters configuration mode. |
||||
|
Step 2 |
call-home reporting {anonymous | contact-email-addr email-address} [http-proxy {ipv4-address | ipv6-address | name} port port-number] Example:Enables the basic configurations for Call Home using a single command.
|
For application and configuration information about the Cisco Smart Call Home service, see the “Getting Started” section of the Smart Call Home User Guide at https://supportforums.cisco.com/community/4816/smart-call-home. This document includes configuration examples for sending Smart Call Home messages directly from your device or through a transport gateway (TG) aggregation point.
Note |
For security reasons, we recommend that you use the HTTPS transport options, due to the additional payload encryption that HTTPS offers. The Transport Gateway software is downloadable from Cisco.com and is available if you require an aggregation point or a proxy for connection to the Internet. |
To enable or disable the Call Home feature, perform these steps:
|
Step 1 |
configure terminal Example:Enters configuration mode. |
|
Step 2 |
service call-home Example:Enables the Call Home feature. |
|
Step 3 |
no service call-home Example:Disables the Call Home feature. |
Each router must include a contact e-mail address (except if Call Home is enabled in anonymous mode). You can optionally include a phone number, street address, contract ID, customer ID, and site ID.
To assign the contact information, perform the following steps:
|
Step 1 |
configure terminal Example:Enters configuration mode. |
||
|
Step 2 |
call-home Example:Enters the Call Home configuration submode. |
||
|
Step 3 |
contact-email-addr email-address Example:Designates your e-mail address. Enter up to 200 characters in e-mail address format with no spaces. |
||
|
Step 4 |
phone-number +phone-number Example:(Optional) Assigns your phone number.
|
||
|
Step 5 |
street-address street-address Example:(Optional) Assigns your street address where RMA equipment can be shipped. Enter up to 200 characters. If you include spaces, you must enclose your entry in quotes (“”). |
||
|
Step 6 |
customer-id text Example:(Optional) Identifies customer ID. Enter up to 64 characters. If you include spaces, you must enclose your entry in quotes (“”). |
||
|
Step 7 |
site-id text Example:(Optional) Identifies customer site ID. Enter up to 200 characters. If you include spaces, you must enclose your entry in quotes (“”). |
||
|
Step 8 |
contract-id text Example:(Optional) Identifies your contract ID for the router. Enter up to 64 characters. If you include spaces, you must enclose your entry in quotes (“”). |
This example shows how to configure contact information:
Router# configure terminal
Enter configuration commands, one per line. End with CNTL/Z.
Router(config)# call-home
Router(cfg-call-home)# contact-email-addr username@example.com
Router(cfg-call-home)# phone-number +1-800-555-4567
Router(cfg-call-home)# street-address “1234 Picaboo Street, Any city, Any state, 12345”
Router(cfg-call-home)# customer-id Customer1234
Router(cfg-call-home)# site-id Site1ManhattanNY
Router(cfg-call-home)# contract-id Company1234
Router(cfg-call-home)# exit
A destination profile contains the required delivery information for an alert notification. At least one destination profile is required. You can configure multiple destination profiles of one or more types.
You can create and define a new destination profile or copy and use the predefined destination profile. If you define a new destination profile, you must assign a profile name.
Note |
If you use the Cisco Smart Call Home service, the destination profile must use the XML message format. |
You can configure these attributes for a destination profile:
Profile name—String that uniquely identifies each user-defined destination profile. The profile name is limited to 31 characters and is not case-sensitive.
Note |
You cannot use all as a profile name. |
Transport method—Transport mechanism, either e-mail or HTTP (including HTTPS), for delivery of alerts.
For user-defined destination profiles, e-mail is the default, and you can enable either or both transport mechanisms. If you disable both methods, e-mail is enabled.
For the predefined Cisco TAC profile, you can enable either transport mechanism, but not both.
Destination address—The actual address related to the transport method to which the alert should be sent.
Message formatting—The message format used for sending the alert. The format options for a user-defined destination profile are long-text, short-text, or XML. The default is XML. For the predefined Cisco TAC profile, only XML is allowed.
Anonymous reporting—You can choose for your customer identity to remain anonymous, and no identifying information is sent.
Subscribing to interesting alert-groups—You can choose to subscribe to alert-groups highlighting your interests.
To create and configure a new destination profile, perform the following steps:
|
Step 1 |
configure terminal Example:Enters configuration mode. |
||
|
Step 2 |
call-home Example:Enters the Call Home configuration submode. |
||
|
Step 3 |
profile name Example:Enters the Call Home destination profile configuration submode for the specified destination profile. If the specified destination profile does not exist, it is created. |
||
|
Step 4 |
[no] destination transport-method {email | http} Example:(Optional) Enables the message transport method. The no option disables the method. |
||
|
Step 5 |
destination address {email email-address | http url} Example:Configures the destination e-mail address or URL to which Call Home messages are sent.
|
||
|
Step 6 |
destination preferred-msg-format {long-text | short-text | xml} Example:(Optional) Configures a preferred message format. The default is XML. |
||
|
Step 7 |
destination message-size-limit bytes Example:(Optional) Configures a maximum destination message size for the destination profile. |
||
|
Step 8 |
active Example:Enables the destination profile. By default, the profile is enabled when it is created. |
||
|
Step 9 |
end Example:Returns to privileged EXEC mode. |
Use the show call-home profile {name | all} command to display the destination profile configuration for the specified profile or all configured profiles.
Router# show call-home profile profile1To create a new destination profile by copying an existing profile, perform these steps:
|
Step 1 |
configure terminal Example:Enters configuration mode. |
|
Step 2 |
call-home Example:Enters the Call Home configuration submode. |
|
Step 3 |
copy profile source-profile target-profile Example:Creates a new destination profile with the same configuration settings as the existing destination profile. |
To set an anonymous profile, perform the following steps:
|
Step 1 |
configure terminal Example:Enters configuration mode. |
||
|
Step 2 |
call-home Example:Enters the Call Home configuration submode. |
||
|
Step 3 |
profile name Example:Enables the profile configuration mode. |
||
|
Step 4 |
anonymous-reporting-only Example:Sets the profile to anonymous mode.
|
An alert group is a predefined subset of Call Home alerts supported in all routers. Different types of Call Home alerts are grouped into different alert groups depending on their type. The following alert groups are available:
Crash
Configuration
Environment
Inventory
Snapshot
Syslog
The triggering events for each alert group are listed in Alert groups Trigger Events and Commands, and the contents of the alert group messages are listed in Message contents.
You can select one or more alert groups to be received by a destination profile.
Note |
A Call Home alert is only sent to destination profiles that have subscribed to the alert group containing that Call Home alert. In addition, the alert group must be enabled. |
To subscribe a destination profile to one or more alert groups, perform the following steps:
|
Step 1 |
call-home Example:In the configuration mode, enter Call Home configuration submode. |
||
|
Step 2 |
alert-group {all | configuration | environment | inventory | syslog | crash | snapshot} Example:Enables the specified alert group. Use the keyword all to enable all alert groups. By default, all alert groups are enabled. |
||
|
Step 3 |
profile name Example:Enters the Call Home destination profile configuration submode for the specified destination profile. |
||
|
Step 4 |
subscribe-to-alert-group all Example:Subscribes to all available alert groups using the lowest severity. You can subscribe to alert groups individually by specific type, as described in Step 6 through Step 11.
|
||
|
Step 5 |
subscribe-to-alert-group configuration [periodic {daily hh:mm | monthly date hh:mm | weekly day hh:mm}] Example:Subscribes this destination profile to the Configuration alert group. The Configuration alert group can be configured for periodic notification, as described in Periodic notification. |
||
|
Step 6 |
subscribe-to-alert-group environment [severity {catastrophic | disaster | fatal | critical | major | minor | warning | notification | normal | debugging}] Example:Subscribes this destination profile to the Environment alert group. The Environment alert group can be configured to filter messages based on severity, as described in Message severity threshold. |
||
|
Step 7 |
subscribe-to-alert-group inventory [periodic {daily hh:mm | monthly date hh:mm | weekly day hh:mm}] Example:Subscribes this destination profile to the Inventory alert group. The Inventory alert group can be configured for periodic notification, as described in Periodic notification. |
||
|
Step 8 |
subscribe-to-alert-group syslog [severity {catastrophic | disaster | fatal | critical | major | minor | warning | notification | normal | debugging}] Example:Subscribes this destination profile to the Syslog alert group. The Syslog alert group can be configured to filter messages based on severity, as described in Message severity threshold . You can specify a text pattern to be matched within each syslog message. If you configure a pattern, a Syslog alert group message is sent only if it contains the specified pattern and meets the severity threshold. If the pattern contains spaces, you must enclose it in quotes (“”). You can specify up to five patterns for each destination profile. |
||
|
Step 9 |
subscribe-to-alert-group crash Example:Subscribes to the Crash alert group in user profile. By default, TAC profile subscribes to the Crash alert group and cannot be unsubscribed. |
||
|
Step 10 |
subscribe-to-alert-group snapshot periodic {daily hh:mm | hourly mm | interval mm | monthly date hh:mm | weekly day hh:mm} Example:Subscribes this destination profile to the Snapshot alert group. The Snapshot alert group can be configured for periodic notification, as described in Periodic notification. By default, the Snapshot alert group has no command to run. You can add commands into the alert group, as described in Configure a Snapshot command list. In doing so, the output of the commands added in the Snapshot alert group will be included in the snapshot message. |
||
|
Step 11 |
exit Example:Exits the Call Home destination profile configuration submode. |
When you subscribe a destination profile to the Configuration, Inventory, or Snapshot alert group, you can choose to receive the alert group messages asynchronously or periodically at a specified time.
The sending period can be:
Daily—Specifies the time of day to send, using an hour:minute format hh:mm, with a 24-hour clock (for example, 14:30).
Weekly—Specifies the day of the week and time of day in the format day hh:mm, where the day of the week is spelled out (for example, Monday).
Monthly—Specifies the numeric date, from 1 to 31, and the time of day, in the format date hh:mm.
Interval—Specifies the interval at which the periodic message is sent, from 1 to 60 minutes.
Hourly—Specifies the minute of the hour at which the periodic message is sent, from 0 to 59 minutes.
Note |
Hourly and by interval periodic notifications are available for the Snapshot alert group only. |
When you subscribe a destination profile to the Environment or Syslog alert group, you can set a threshold for the sending of alert group messages based on the level of severity of the message. Any message with a value lower than the destination profile specified threshold is not sent to the destination.
The severity threshold is configured using the keywords listed in the table. The severity threshold ranges from catastrophic (level 9, highest level of urgency) to debugging (level 0, lowest level of urgency). If no severity threshold is configured for the Syslog or Environment alert groups, the default is debugging (level 0). The Configuration and Inventory alert groups do not allow severity configuration; severity is always set as normal.
Note |
Call Home severity levels are not the same as system message logging severity levels. |
| Level | Keyword | Syslog Level | Description |
|---|---|---|---|
| 9 | catastrophic | — | Network-wide catastrophic failure. |
| 8 | disaster | — | Significant network impact. |
| 7 | fatal | Emergency (0) | System is unusable. |
| 6 | critical | Alert (1) | Critical conditions, immediate attention needed. |
| 5 | major | Critical (2) | Major conditions. |
| 4 | minor | Error (3) | Minor conditions. |
| 3 | warning | Warning (4) | Warning conditions. |
| 2 | notification | Notice (5) | Basic notification and informational messages. Possibly independently insignificant. |
| 1 | normal | Information (6) | Normal event signifying return to normal state. |
| 0 | debugging | Debug (7) | Debugging messages. |
To configure a snapshot command list, perform the following steps:
|
Step 1 |
configure terminal Example:Enters configuration mode. |
|
Step 2 |
call-home Example:Enters Call Home configuration submode. |
|
Step 3 |
[no | default] alert-group-config snapshot Example:Enters snapshot configuration mode. The no or default command will remove all snapshot command. |
|
Step 4 |
[no | default] add-command command string Example:Adds the command to the Snapshot alert group. The no or default command removes the corresponding command.
|
|
Step 5 |
exit Example:Exits and saves the configuration. |
To use the e-mail message transport, you must configure at least one Simple Mail Transfer Protocol (SMTP) e-mail server address. You can configure the from and reply-to e-mail addresses, and you can specify up to four backup e-mail servers.
Note the following guidelines when configuring general e-mail options:
Backup e-mail servers can be defined by repeating the mail-server command using different priority numbers.
The mail-server priority number parameter can be configured from 1 to 100. The server with the highest priority (lowest priority number) is tried first.
|
Step 1 |
configure terminal Example:Enters configuration mode. |
||
|
Step 2 |
call-home Example:Enters Call Home configuration submode. |
||
|
Step 3 |
mail-server [{ipv4-address | ipv6-address} | name] priority number Example:Assigns an e-mail server address and its relative priority among configured e-mail servers. Provide either of these:
Assign a priority number between 1 (highest priority) and 100 (lowest priority). |
||
|
Step 4 |
sender from email-address Example:(Optional) Assigns the e-mail address that appears in the from field in Call Home e-mail messages. If no address is specified, the contact e-mail address is used. |
||
|
Step 5 |
sender reply-to email-address Example:(Optional) Assigns the e-mail address that appears in the reply-to field in Call Home e-mail messages. |
||
|
Step 6 |
source-interface interface-name Example:Assigns the source interface name to send call-home messages.
|
||
|
Step 7 |
vrf vrf-name Example:(Optional) Specifies the VRF instance to send call-home e-mail messages. If no vrf is specified, the global routing table is used.
|
The following example shows the configuration of general e-mail parameters, including a primary and secondary e-mail server:
Router#configure terminal
Enter configuration commands, one per line. End with CNTL/Z.
Router(config)#call-home
Router(cfg-call-home)#mail-server smtp.example.com priority 1
Router(cfg-call-home)#mail-server 192.0.2.1 priority 2
Router(cfg-call-home)#sender from username@example.com
Router(cfg-call-home)#sender reply-to username@example.com
Router(cfg-call-home)#source-interface loopback1
Router(cfg-call-home)#vrf vpn1
Router(cfg-call-home)#exit
Router(config)#Rate Limit specifies the maximum number of Call Home messages that a device is allowed to send per minute. This setting helps control the volume of messages sent to avoid overwhelming the network or the receiving system.
|
Step 1 |
configure terminal Example:Enters configuration mode. |
|
Step 2 |
call-home Example:Enters Call Home configuration submode. |
|
Step 3 |
rate-limit number Example:Specifies a limit on the number of messages sent per minute.
|
An HTTP proxy server acts as an intermediary between a client device and a web server, intercepting requests from the client and forwarding them to the web server on the client's behalf. This task provides details on configuring an HTTP proxy Server for sending Call Home HTTP(S) messages to a destination.
|
Step 1 |
configure terminal Example:Enters configuration mode. |
|
Step 2 |
call-home Example:Enters Call Home configuration submode. |
|
Step 3 |
http-proxy {ipv4-address | ipv6-address | name} port port-number Example:Specifies the proxy server for the HTTP request. |
AAA authorization is needed to control and limit the services and resources a user can access after they have been authenticated. It enforces policies by determining what activities, resources, or services a user is permitted to use based on their user profile. To specify an HTTP proxy server for sending Call Home HTTP(S) messages to a destination, use these steps:
|
Step 1 |
configure terminal Example:Enters configuration mode. |
||
|
Step 2 |
call-home Example:Enters Call Home configuration submode. |
||
|
Step 3 |
aaa-authorization Example:Enables AAA authorization.
|
||
|
Step 4 |
aaa-authorization [username username] Example:Specifies the username for authorization.
|
Syslog Throttling is used to control and limit the sending of repetitive syslog messages. When syslog throttling is enabled, it prevents the device from sending the same Call Home syslog messages repeatedly, which helps reduce unnecessary log traffic and avoids overwhelming the management systems with duplicate alerts.
|
Step 1 |
configure terminal Example:Enters configuration mode. |
||
|
Step 2 |
call-home Example:Enters Call Home configuration submode. |
||
|
Step 3 |
[no] syslog-throttling Example:Enables or disables call-home syslog message throttling and avoids sending repetitive call-home syslog messages.
|
The data-privacy command scrubs data, such as IP addresses, from running configuration files to protect the privacy of customers. Enabling the data-privacy command can affect CPU utilization when scrubbing a large amount of data. Currently, the show command output is not being scrubbed except for configuration messages in the outputs for the show running-config all and the show startup-config data commands.
|
Step 1 |
configure terminal Example:Enters configuration mode. |
||||
|
Step 2 |
call-home Example:Enters Call Home configuration submode. |
||||
|
Step 3 |
data-privacy {level {normal | high} | hostname} Example:Scrubs data from running configuration file to protect the privacy of the user. The default data-privacy level is normal.
|
You can manually send several types of Call Home communications. To send Call Home communications, perform the tasks in this section. This section contains the following subsections:
Send a Call Home Test Message Manually
Send Call Home Alert Group Messages Manually
Submit Call Home Analysis and Report Requests
Manually Send Command Output Message for One Command or a Command List
You can use the call-home test command to send a user-defined Call Home test message.
To manually send a Call Home test message, execute this command:
|
call-home test [“test-message”] profile name Example:Sends a test message to the specified destination profile. The user-defined test message text is optional but must be enclosed in quotes (“”) if it contains spaces. If no user-defined message is configured, a default message is sent. |
You can use the call-home send command to manually send a specific alert group message.
Note the following guidelines when manually sending a Call Home alert group message:
Only the crash, snapshot, configuration, and inventory alert groups can be sent manually.
When you manually trigger a crash, snapshot, configuration, or inventory alert group message and you specify a destination profile name, a message is sent to the destination profile regardless of the profile’s active status, subscription status, or severity setting.
When you manually trigger a crash, snapshot, configuration, or inventory alert group message and do not specify a destination profile name, a message is sent to all active profiles that have either a normal or periodic subscription to the specified alert group.
To manually trigger Call Home alert group messages, perform these steps:
|
Step 1 |
call-home send alert-group snapshot [profile name] Example:Sends a snapshot alert group message to one destination profile if specified, or to all subscribed destination profiles. |
|
Step 2 |
call-home send alert-group crash [profile name] Example:Sends a crash alert group message to one destination profile if specified, or to all subscribed destination profiles. |
|
Step 3 |
call-home send alert-group configuration [profile name] Example:Sends a configuration alert group message to one destination profile if specified, or to all subscribed destination profiles. |
|
Step 4 |
call-home send alert-group inventory [profile name] Example:Sends an inventory alert group message to one destination profile if specified, or to all subscribed destination profiles. |
You can use the call-home request command to submit information about your system to Cisco to receive helpful analysis and report information specific to your system. You can request a variety of reports, including security alerts, known bugs, best practices, and command references.
Note the following guidelines when manually sending Call Home analysis and report requests:
If a profile name is specified, the request is sent to the profile. If no profile is specified, the request is sent to the Cisco TAC profile. The recipient profile does not need to be enabled for the call-home request. The profile should specify the e-mail address where the transport gateway is configured so that the request message can be forwarded to the Cisco TAC and the user can receive the reply from the Smart Call Home service.
The ccoid user-id is the registered identifier of the Smart Call Home user. If the user-id is specified, the response is sent to the e-mail address of the registered user. If no user-id is specified, the response is sent to the contact e-mail address of the device.
To submit a request for analysis and report information from the Cisco Output Interpreter tool, perform the following steps:
|
Step 1 |
call-home request output-analysis “show-command” [profile name] [ccoid user-id] Example:Sends the output of the specified show command for analysis. The show command must be contained in quotes (“”). |
|
Step 2 |
call-home request {config-sanity | bugs-list | command-reference | product-advisory} [profile name] [ccoid user-id] Example:Sends the output of a predetermined set of commands such as the show running-config all, show version or show module commands, for analysis. In addition, the call home request product-advisory command includes all inventory alert group commands. The keyword specified after request specifies the type of report requested. |
Based on the keyword specifying the type of report requested, the following information is returned:
config-sanity—Information on best practices as related to the current running configuration.
bugs-list—Known bugs in the running version and in the currently applied features.
command-reference—Reference links to all commands in the running configuration.
product-advisory—Product Security Incident Response Team (PSIRT) notices, End of Life (EOL) or End of Sales (EOS) notices, or field notices (FN) that may affect the devices in your network.
The following example shows a request for analysis of a user-specified show command:
Router#call-home request output-analysis "show diag" profile TG
You can use the call-home send command to execute an IOS command or a list of IOS commands and send the command output through HTTP or e-mail protocol.
Note the following guidelines when sending the output of a command:
The specified IOS command or list of IOS commands can be any run command, including commands for all modules. The command must be contained in quotes (“”).
If the e-mail option is selected using the “email” keyword and an e-mail address is specified, the command output is sent to that address. If neither the e-mail nor the HTTP option is specified, the output is sent in long-text format with the specified service request number to the Cisco TAC (attach@cisco.com).
If neither the “email” nor the “http” keyword is specified, the service request number is required for both long-text and XML message formats and is provided in the subject line of the e-mail.
If the HTTP option is specified, the CiscoTac-1 profile destination HTTP or HTTPS URL is used as the destination. The destination e-mail address can be specified so that Smart Call Home can forward the message to the e-mail address. The user must specify either the destination e-mail address or an SR number but they can also specify both.
To execute a command and send the command output, perform the following step:
|
call-home send {cli command | cli list} [email email msg-format {long-text | xml} | http {destination-email-address email}] [tac-service-request SR#] Example:Executes the CLI or CLI list and sends output via e-mail or HTTP.
|
The following example shows how to send the output of a command to a user-specified e-mail address:
Router#call-home send “show diag” email support@example.com
The following example shows the command output sent in long-text format to attach@cisco.com, with the SR number specified:
Router#call-home send “show version; show run” tac-service-request 123456
The following example shows the command output sent in XML message format to callhome@cisco.com:
Router#call-home send “show version; show run” email callhome@cisco.com msg-format xml
The following example shows the command output sent in XML message format to the Cisco TAC backend server, with the SR number specified:
Router#call-home send “show version; show run” http tac-service-request 123456
The following example shows the command output sent to the Cisco TAC backend server through the HTTP protocol and forwarded to a user-specified email address:
Router#call-home send “show version; show run” http destination-email-address user@company.com
Diagnostic signatures 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.
Diagnostic signatures provide the ability to define more types of events and trigger types than the standard Call Home feature supports. The Diagnostic signatures 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. Diagnostic signatures files are formatted files that collate the knowledge of diagnostic events and provide methods to troubleshoot these events.
Diagnostic signatures 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.
You must assign one or more DSs to the device. For more information on how to assign DSs to devices, see .
HTTP/Secure HTTP (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.
Note |
If you configure the trustpool feature, the CA certificate is not required. |
To download the diagnostic signature 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 diagnostic signature.
Cisco devices 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 diagnostic signature update requests to download these files: regular and forced-download.
Regular download requests diagnostic signature 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 diagnostic signature is different from the version of the diagnostic signature on the device.
Periodic download is only started after there is any diagnostic signature assigned to the device from diagnostic signature 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 diagnostic signature download/update. In a diagnostic signature update request message, the status and revision number of the diagnostic signature is included such that only a diagnostic signature with the latest revision number is downloaded.
Forced-download downloads a specific diagnostic signature or a set of diagnostic signatures. 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 diagnostic signature file is downloaded irrespective of the current DS file version on the device.
The diagnostic signature file is digitally signed, and signature verification is performed on every downloaded diagnostic signature file to make sure it is from a trusted source.
The diagnostic signature feature is enabled by default in Cisco software. These steps outline the workflow for using diagnostic signatures
The workflow of Diagnostic Signature involves these stages.
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 diagnostic signature. The event specification format is one of the following two types:
In single event detection, only one event detector is defined within a diagnostic signature. The event specification format is one of these types:
diagnostic signature event 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 diagnostic signature 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 diagnostic signature is triggered when a Tool Command Language (Tcl) script is used to specify event detection types.
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.
The diagnostic signature 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 diagnostic signature that are used to customize the files.
Diagnostic signature actions are categorized into these types:
call-home
command
emailto
script
Diagnostic signature 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 diagnostic signature ID as the message sub-type.
The commands defined for the diagnostic signature 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.
Variables are referenced within a diagnostic signature and are used to customize the diagnostic signature file. All diagnostic signature variable names have the prefix ds_ to separate them from other variables. These are the supported diagnostic signature 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 Diagnostic signatures environment variables. If the Diagnostic signatures file contains unresolved environment variables, this Diagnostic signatures 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 Diagnostic signatures indicates pending.
Regular expression variable: values assigned from a regular expression pattern match with predefined CLI command outputs. The value is assigned during the Diagnostic signatures run.
Syslog event variable: values assigned during a syslog event detection in the Diagnostic signatures file. This variable is valid only for syslog event detection.
Configure the Call Home Service feature to set attributes such as the contact email address where notifications related with diagnostic signatures are sent and destination HTTP/secure HTTP (HTTPS) URL to download the diagnostic signatures 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 that you use it. If used, you only need to change the destination transport-method to the http setting. |
|
Step 1 |
configure terminal Example:Enters global configuration mode. |
||
|
Step 2 |
service call-home Example:Enables Call Home service on a device. |
||
|
Step 3 |
call-home Example:Enters call-home configuration mode for the configuration of Call Home settings. |
||
|
Step 4 |
contact-email-addr email-address Example:(Optional) Assigns an email address to be used for Call Home customer contact. |
||
|
Step 5 |
mail-server {ipv4-addr | name} priority number Example:(Optional) Configures a Simple Mail Transfer Protocol (SMTP) email server address for Call Home. This command is only used when sending email is part of the actions defined in any DS. |
||
|
Step 6 |
profile profile-name Example:Configures a destination profile for Call Home and enters call-home profile configuration mode. |
||
|
Step 7 |
destination transport-method {email | http} Example:Specifies a transport method for a destination profile in the Call Home.
|
||
|
Step 8 |
destination address {email address | http url} Example:Configures the address type and location to which call-home messages are sent.
|
||
|
Step 9 |
subscribe-to-alert-group inventory [periodic {daily hh:mm | monthly day hh:mm | weekly day hh:mm}] Example:Configures a destination profile to send messages for the Inventory alert group for Call Home.
|
Configure the Call Home feature to set attributes for the Call Home profile. You can either use the default CiscoTAC-1 profile or use the newly-created user profile.
|
Step 1 |
call-home Example:Enters call-home configuration mode for the configuration of Call Home settings. |
|
Step 2 |
diagnostic-signature Example:Enters call-home diagnostic signature mode. |
|
Step 3 |
profile ds-profile-name Example:Specifies the destination profile on a device that DS uses. |
|
Step 4 |
environment ds_env-var-name ds-env-var-value Example:Sets the environment variable value for DS on a device. |
|
Step 5 |
end Example:Exits call-home diagnostic signature mode and returns to privileged EXEC mode. |
|
Step 6 |
call-home diagnostic-signature [{deinstall | download} {ds-id | all} | install ds-id] Example:Downloads, installs, and uninstalls diagnostic signature files on a device. |
|
Step 7 |
show call-home diagnostic-signature [ds-id {actions | events | prerequisite | prompt | variables | failure | statistics | download}] Example:Displays the call-home diagnostic signature information. |
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.
Router>enable
Router#configure terminal
Router(config)#service call-home
Router(config)#call-home
Router(cfg-call-home)#contact-email-addr userid@example.com
Router(cfg-call-home)#mail-server 10.1.1.1 priority 4
Router(cfg-call-home)#profile user-1
Router(cfg-call-home-profile)#destination transport-method http
Router(cfg-call-home-profile)#destination address http https://tools.cisco.com/its/service/oddce/services/DDCEService
Router(cfg-call-home-profile)#subscribe-to-alert-group inventory periodic daily 14:30
Router(cfg-call-home-profile)#exit
Router(cfg-call-home)#diagnostic-signature
Router(cfg-call-home-diag-sign)#profile user1
Router(cfg-call-home-diag-sign)#environment ds_env1 envarval
Router(cfg-call-home-diag-sign)#end
The following is sample output from the show call-home diagnostic-signature command for the configuration displayed above:
outer#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
You can use variations of the show call-home command to display Call Home configuration information.
Follow these steps to display Call Home configuration information:
|
Step 1 |
Enter show call-home command to display a summary of the Call Home configuration. Example: |
|
Step 2 |
Enter show call-home detail command to display detailed Call Home configuration. Example: |
|
Step 3 |
Enter show call-home alert-group command to view available alert groups and their status. Example: |
|
Step 4 |
Enter show call-home mail-server status command to check the availability of the configured email servers. Example: |
|
Step 5 |
Enter show call-home profile { all | name } command to display configuration for all or specific destination profiles. Example: |
|
Step 6 |
Enter the show call-home statistics [ detail | profile profile-name ] command to view statistics of Call Home events. Example: |
The system displays the requested information about Call Home configuration, profiles, alert groups, email server status, or statistics, enabling you to review or troubleshoot the Call Home functionality.
The table lists the default Call Home settings.
|
Parameters |
Default |
|---|---|
|
Call Home feature status |
Disabled |
|
User-defined profile status |
Active |
|
Predefined Cisco TAC profile status |
Inactive |
|
Transport method |
|
|
Message format type |
XML |
|
Destination message size for a message sent in long text, short text, or XML format |
3,145,728 |
|
Alert group status |
Enabled |
|
Call Home message severity threshold |
Debug |
|
Message rate limit for messages per minute |
20 |
|
AAA Authorization |
Disabled |
|
Call Home syslog message throttling |
Enabled |
|
Data privacy level |
Normal |
Call Home trigger events are grouped into alert groups. Each alert group is assigned commands that execute when an event occurs. The output of these commands is included in the transmitted message.
| Alert Group | Call Home Trigger Event | Syslog Event | Severity | Description and Commands Executed |
|---|---|---|---|---|
|
Crash |
SYSTEM_ CRASH |
– | – |
These are events related to a software crash. The following commands are executed: show version show logging show region show inventory show stack crashinfo file (this command shows the contents of the crashinfo file) |
| – |
TRACEBACK |
– | – |
Detects software traceback events. The following commands are executed: show version show logging show region show stack |
|
Configuration |
– | – | – |
User-generated request for configuration or configuration change event. The following commands are executed: show platform show inventory show running-config all show startup-config show version |
|
Environmental |
– | – | – |
Events related to power, fan, and environment sensing elements such as temperature alarms. The following commands are executed: show environment show inventory show platform show logging |
| – | – |
SHUT |
0 |
Environmental Monitor initiated shutdown. |
| – | – |
ENVCRIT |
2 |
Temperature or voltage measurement exceeded critical threshold. |
| – | – |
BLOWER |
3 |
The required number of fan trays is not present. |
| – | – |
ENVWARN |
4 |
Temperature or voltage measurement exceeded warning threshold. |
| – | – |
RPSFAIL |
4 |
Power supply may have a failed channel. |
| – |
ENVM |
PSCHANGE |
6 |
Power supply name change. |
| – | – |
PSLEV |
6 |
Power supply state change. |
| – | – |
PSOK |
6 |
Power supply now appears to be working correctly. |
|
Inventory |
– | – | – |
Inventory status should be provided whenever a unit is cold-booted or when FRUs are inserted or removed. This is considered a noncritical event, and the information is used for status and entitlement. Commands executed for all Inventory messages sent in anonymous mode and for Delta Inventory message sent in full registration mode: show diag all eeprom detail show version show inventory oid show platform Commands executed for Full Inventory message sent in full registration mode: show platform show diag all eeprom detail show version show inventory oid show bootflash: all show data-corruption show interfaces show file systems show memory statistics show process memory show process cpu show process cpu history show license udi show license detail show buffers |
| – |
HARDWARE_ REMOVAL |
REMCARD |
6 |
Card removed from slot %d, interfaces disabled. |
| – |
HARDWARE_ INSERTION |
INSCARD |
6 |
Card was inserted in slot %d, and interfaces were administratively shut down. |
|
Syslog |
– | – | – |
Event logged to syslog. The following commands are executed: show inventory show logging |
| – |
SYSLOG |
LOG_EMERG |
0 |
System is unusable. |
| – |
SYSLOG |
LOG_ALERT |
1 |
Action must be taken immediately. |
| – |
SYSLOG |
LOG_CRIT |
2 |
Critical conditions. |
| – |
SYSLOG |
LOG_ERR |
3 |
Error conditions. |
| – |
SYSLOG |
LOG_WARNING |
4 |
Warning conditions. |
| – |
SYSLOG |
LOG_NOTICE |
5 |
Normal but significant condition. |
| – |
SYSLOG |
LOG_INFO |
6 |
Informational. |
| – |
SYSLOG |
LOG_DEBUG |
7 |
Debug-level messages. |
|
Test |
– |
TEST |
– |
User-generated test message. The following commands are executed: show platform show inventory show version |
This section consists of tables which list the content formats of alert group messages.
The following table lists the content fields of a short text message.
| Data Item | Description |
|---|---|
|
Device identification |
Configured device name. |
|
Date/time stamp |
Time stamp of the triggering event. |
|
Error isolation message |
Plain English description of triggering event. |
|
Alarm urgency level |
Error level such as that applied to a system message. |
The following table shows the content fields that are common to all long text and XML messages. The fields specific to a particular alert group message are inserted at a point between the common fields. The insertion point is identified in the table.
|
Data Item (Plain Text and XML) |
Description (Plain Text and XML) |
Call-Home Message Tag (XML Only) |
|---|---|---|
|
Time stamp |
Date and time stamp of event in ISO time notation: YYYY-MM-DD HH:MM:SS GMT+HH:MM. |
CallHome/EventTime |
|
Message name |
Name of message. Specific event names are listed in the Alert group trigger events and commands. |
For short text message only |
|
Message type |
Specifically “Call Home”. |
CallHome/Event/Type |
|
Message subtype |
Specific type of message: full, delta, test |
CallHome/Event/SubType |
|
Message group |
Specifically “reactive”. Optional because default is “reactive”. |
For long-text message only |
|
Severity level |
Severity level of message (see Message severity threshold). |
Body/Block/Severity |
|
Source ID |
Product type for routing through the workflow engine. This is typically the product family name. |
For long-text message only |
|
Device ID |
Unique device identifier (UDI) for end device generating message. This field should be empty if the message is nonspecific to a fabric switch. The format is type@Sid@serial.
Example: CISCO3845@C@12345678 |
CallHome/CustomerData/ ContractData/DeviceId |
|
Customer ID |
Optional user-configurable field used for contract information or other ID by any support service. |
CallHome/CustomerData/ ContractData/CustomerId |
|
Contract ID |
Optional user-configurable field used for contract information or other ID by any support service. |
CallHome/CustomerData/ ContractData/CustomerId |
|
Site ID |
Optional user-configurable field used for Cisco-supplied site ID or other data meaningful to alternate support service. |
CallHome/CustomerData/ ContractData/CustomerId |
|
Server ID |
If the message is generated from the fabric switch, this is the unique device identifier (UDI) of the switch.
Example: CISCO3845@C@12345678 |
For long text message only. |
|
Message description |
Short text describing the error. |
CallHome/MessageDescription |
|
Device name |
Node that experienced the event. This is the host name of the device. |
CallHome/CustomerData/ SystemInfo/NameName |
|
Contact name |
Name of person to contact for issues associated with the node experiencing the event. |
CallHome/CustomerData/ SystemInfo/Contact |
|
Contact e-mail |
E-mail address of person identified as contact for this unit. |
CallHome/CustomerData/ SystemInfo/ContactEmail |
|
Contact phone number |
Phone number of the person identified as the contact for this unit. |
CallHome/CustomerData/ SystemInfo/ContactPhoneNumber |
|
Street address |
Optional field containing street address for RMA part shipments associated with this unit. |
CallHome/CustomerData/ SystemInfo/StreetAddress |
|
Model name |
Model name of the router. This is the “specific model as part of a product family name. |
CallHome/Device/Cisco_Chassis/Model |
|
Serial number |
Chassis serial number of the unit. |
CallHome/Device/Cisco_Chassis/ SerialNumber |
|
Chassis part number |
Top assembly number of the chassis. |
CallHome/Device/ Cisco_Chassis/AdditionalInformation/ AD@name=“PartNumber” |
|
System object ID |
System Object ID that uniquely identifies the system. |
CallHome/Device/ Cisco_Chassis/AdditionalInformation/ AD@name=“sysObjectID” |
|
System description |
System description for the managed element. |
CallHome/Device/ Cisco_Chassis/AdditionalInformation/ AD@name=“sysDescr” |
The following table shows the inserted fields specific to a particular alert group message.
Note |
The following fields may be repeated if multiple commands are executed for this alert group. |
|
Command output name |
Exact name of the issued command. |
/aml/Attachments/Attachment/Name |
|---|---|---|
|
Attachment type |
Attachment type. Usually “inline”. |
/aml/Attachments/Attachment@type |
|
MIME type |
Normally “text” or “plain” or encoding type. |
/aml/Attachments/Attachment/ Data@encoding |
|
Command output text |
Output of command automatically executed (see Alert group trigger events and commands). |
/mml/attachments/attachment/atdata |
The following table shows the inserted content fields for reactive messages (system failures that require a TAC case) and proactive messages (issues that might result in degraded system performance).
| Data Item (Plain Text and XML) | Description (Plain Text and XML) | Call-Home Message Tag (XML Only) |
|---|---|---|
|
Chassis hardware version |
Hardware version of chassis |
CallHome/Device/Cisco_Chassis/ HardwareVersion |
|
Supervisor module software version |
Top-level software version. |
CallHome/Device/Cisco_Chassis/ AdditionalInformation/AD@name= “SoftwareVersion” |
|
Affected FRU name |
Name of the affected FRU generating the event message. |
CallHome/Device/Cisco_Chassis/ Cisco_Card/Model |
|
Affected FRU serial number |
Serial number of affected FRU |
CallHome/Device/Cisco_Chassis/ Cisco_Card/SerialNumber |
|
Affected FRU part number |
Part number of affected FRU |
CallHome/Device/Cisco_Chassis/ Cisco_Card/PartNumber |
|
FRU slot |
Slot number of FRU generating the event message |
CallHome/Device/Cisco_Chassis/ Cisco_Card/LocationWithinContainer |
|
FRU hardware version |
Hardware version of affected FRU |
CallHome/Device/Cisco_Chassis/ Cisco_Card/HardwareVersion |
|
FRU software version |
Software version(s) running on affected FRU |
CallHome/Device/Cisco_Chassis/ Cisco_Card/SoftwareIdentity/ VersionString |
The following table shows the inserted content fields for an inventory message.
| Data Item (Plain Text and XML) | Description (Plain Text and XML) | Call-Home Message Tag (XML Only) |
|---|---|---|
|
Chassis hardware version |
Hardware version of chassis |
CallHome/Device/Cisco_Chassis/ HardwareVersion |
|
Supervisor module software version |
Top-level software version |
CallHome/Device/Cisco_Chassis/ AdditionalInformation/AD@name= “SoftwareVersion” |
|
FRU name |
Name of the affected FRU generating the event message |
CallHome/Device/Cisco_Chassis/ Cisco_Card/Model |
|
FRU s/n |
Serial number of FRU |
CallHome/Device/Cisco_Chassis/ Cisco_Card/SerialNumber |
|
FRU part number |
Part number of FRU |
CallHome/Device/Cisco_Chassis/ Cisco_Card/PartNumber |
|
FRU slot |
Slot number of FRU |
CallHome/Device/Cisco_Chassis/ Cisco_Card/LocationWithinContainer |
|
FRU hardware version |
Hardware version of FRU |
CallHome/Device/Cisco_Chassis/ CiscoCard/HardwareVersion |
|
FRU software version |
Software version(s) running on FRU |
CallHome/Device/Cisco_Chassis /Cisco_Card/SoftwareIdentity/ VersionString |
Feedback