CNS Image Agent [Cisco IOS Software Releases 12.3 Mainline]

Table Of Contents

CNS Image Agent

Contents

Prerequisites for the CNS Image Agent

Restrictions for the CNS Image Agent

Information About the CNS Image Agent

CNS

CNS Image Agent

How to Configure the CNS Image Agent

Configuring the CNS Image Agent Using the CLI

CNS Image Agent ID

Prerequisites

What to Do Next

Configuring the CNS Image Agent to Use the CNS Event Bus

Troubleshooting Tips

Polling the Server Using the CLI

Prerequisites

Troubleshooting Tips

Polling the Server Using Command Scheduler

Command Scheduler Policy Lists

Prerequisites

Troubleshooting CNS Image Agent Operation

Examples

Sample Output for the show cns image status Command

Sample Output for the show cns image connections Command

Sample Output for the show cns image inventory Command

Sample Output for the debug cns image Command

Configuration Examples for the CNS Image Agent

Configuring the CNS Image Agent Examples

Polling the Server Examples

Where to Go Next

Additional References

Related Documents

Standards

MIBs

RFCs

Technical Assistance

Command Reference

clear cns image connections

clear cns image status

cns id

cns image

cns image password

cns image retrieve

cns image retry

debug cns image

show cns image connections

show cns image inventory

show cns image status

CNS Image Agent

The CNS Image Agent feature is an infrastructure in Cisco IOS software to enable automated installation and activation of Cisco IOS images on Cisco IOS networking devices.

Feature Specifications for the CNS Image Agent

Feature History

Release

Modification

12.3(1)

This feature was introduced.

Supported Platforms

For platforms supported in Cisco IOS Release 12.3(1), consult Cisco Feature Navigator.

Finding Support Information for Platforms and Cisco IOS Software Images

Use Cisco Feature Navigator to find information about platform support and Cisco IOS software image support. Access Cisco Feature Navigator at http://www.cisco.com/go/fn. You must have an account on Cisco.com. If you do not have an account or have forgotten your username or password, click Cancel at the login dialog box and follow the instructions that appear.

Contents

•Prerequisites for the CNS Image Agent

•Restrictions for the CNS Image Agent

•Information About the CNS Image Agent

•How to Configure the CNS Image Agent

•Configuration Examples for the CNS Image Agent

•Where to Go Next

•Additional References

•Command Reference

Prerequisites for the CNS Image Agent

•Determine where to store the Cisco IOS images on a file server to make the image available to many other networking devices. If the CNS Event Bus is to be used to store and distribute the images, the CNS event agent must be configured.

•Set up a file server to enable the networking devices to download the new images. Protocols such as TFTP, HTTP, HTTPS, and rcp can be used.

•Determine how to handle error messages generated by CNS image agent operations. Error messages can be sent to the CNS Event Bus or an HTTP or HTTPS URL.

Restrictions for the CNS Image Agent

During automated image loading operations you must try to prevent the Cisco IOS device from losing connectivity with the file server that is providing the image. Image reloading is subject to memory issues and connection issues. Boot options must also be configured to allow the Cisco IOS device to boot another image if the first image reload fails. For more details refer to the "File Management" section of the Release 12.2 Cisco IOS Configuration Fundamentals Configuration Guide.

Information About the CNS Image Agent

To configure the CNS image agent, you need to understand the following concepts:

•CNS

•CNS Image Agent

CNS

CNS is a foundation technology for linking users to networking services. Existing CNS features include CNS configuration and event agents and a flow-through provisioning structure. The configuration and event agents use a CNS Configuration Engine to provide methods for automating initial Cisco IOS device configurations, incremental configurations, and synchronized configuration updates, and it reports the status of the configuration load as an event to which a network monitoring or workflow application can subscribe. The CNS flow-through provisioning uses the CNS configuration and event agents to provide an automated workflow, eliminating the need for an on-site technician.

CNS Image Agent

Administrators maintaining large networks of Cisco IOS devices need an automated mechanism to load image files onto large numbers of remote devices. Existing network management applications are useful to determine which images to run and how to manage images received from the Cisco online software center. Other image distribution solutions do not scale to cover thousands of devices and cannot distribute images to devices behind a firewall or using Network Address Translation (NAT). The CNS image agent enables the managed device to initiate a network connection and request an image download allowing devices using NAT, or behind firewalls, to access the image server.

The CNS image agent can be configured to use the CNS Event Bus. To use the CNS Event Bus, the CNS event agent must be enabled and connected to the CNS event gateway in the CNS Configuration Engine. The CNS image agent can also use an HTTP server that understands the CNS image agent protocol. Deployment of CNS image agent operations can use both the CNS Event Bus and an HTTP server.

How to Configure the CNS Image Agent

This section contains the following procedures:

•Configuring the CNS Image Agent Using the CLI (optional)

•Configuring the CNS Image Agent to Use the CNS Event Bus (optional)

•Polling the Server Using the CLI (optional)

•Polling the Server Using Command Scheduler (optional)

Configuring the CNS Image Agent Using the CLI

Use this task to configure CNS image agent parameters using command-line interface (CLI) commands.

CNS Image Agent ID

CNS uses a unique identifier to identify an image agent associated with that Cisco IOS device. Using the same process as CNS event and configuration agents, the configuration of the cns id command determines whether an IP address or MAC address of a specified interface, the hardware serial hardware number of the device, an arbitrary text string, or the host name of the device is used as the image ID. By default, the system uses the host name of the device.

The CNS image ID is sent in the content of the messages sent by the image agent and allows an application to know the unique image ID of the Cisco IOS device that generated the message. A password can be configured and associated with the image ID in the image agent messages.

Prerequisites

•To configure the CNS image agent to use HTTP or HTTPS to communicate with an image server, you need to know the URL for the image server and the URL to which status messages can be sent.

•If you are using HTTPS to communicate with the image server, you must set up security certificates to allow the server to be authenticated by the image agent when the connection is established.

SUMMARY STEPS

1. enable

2. configure terminal

3. cns id type number {dns-reverse | ipaddress | mac-address} [event] [image]
or
cns id {hardware-serial | hostname | string text} [event] [image]

4. cns image [server server-url [status status-url]]

5. cns image password image-password

6. cns image retry seconds

7. exit

DETAILED STEPS
Command or Action

Purpose

Step 1

enable
Example:

Router> enable

Enables privileged EXEC mode.

•Enter your password if prompted.

Step 2

configure terminal
Example:

Router# configure terminal

Enters global configuration mode.
Step 3
cns id type number {dns-reverse | ipaddress | mac-address} [event] [image]
or

cns id {hardware-serial | hostname | string text} [event] [image]
Example:

Router(config)# cns id fastethernet 0/1 ipaddress image
or

Example:

Router(config)# cns id hardware-serial image
Specifies a unique CNS ID and interface type and number from which to retrieve the unique ID.

or

Specifies a unique CNS ID assigned from the hardware serial number, device host name, or an arbitrary text string.

The following information applies to either version of the syntax.

•Use the event keyword to specify an event agent ID.

•Use the image keyword to specify an image agent ID.

•If no keywords are used, the configuration agent ID is configured.
Step 4

cns image [server server-url] status status-url
Example:

Router(config)# cns image server https://10.21.2.3/cns/imgsvr status https://10.21.2.3/cns/status/

Enables CNS image agent services and specifies the URL of the image distribution server.

•Use the optional status keyword and status-url argument to specify the URL of a web server to which error messages are written.

•If the status keyword and status-url argument are not specified, status messages are sent as events on the CNS Event Bus. To view the status messages on the CNS Event Bus, the CNS event agent must be configured.

Step 5

cns image password password
Example:

Router(config)# cns image password abctext

(Optional) Specifies a password for CNS image agent services.

•If a password is configured, the password is included with the image ID in CNS image agent messages sent out by the image agent. The receiver of these messages can use this information to authenticate the sending device.

Step 6

cns image retry seconds
Example:

Router(config)# cns image retry 240

(Optional) Specifies an image upgrade retry interval in seconds.

•The default interval is 60 seconds.

Step 7

exit
Example:

Router(config)# exit

Exits global configuration mode, and returns the router to privileged EXEC mode.
What to Do Next

Proceed to the "Polling the Server Using the CLI" section to connect to the web server and download an image.

If any of the commands in the task fail, proceed to the "Troubleshooting CNS Image Agent Operation" section to try to determine the problem.

Configuring the CNS Image Agent to Use the CNS Event Bus

Use this task to configure CNS image agent parameters to use the CNS Event Bus. When the CNS image agent and event agent are both enabled, the CNS Event Bus is listened to by the software. For more details on the CNS event agent and CNS Event Bus refer to the CNS Event Agent feature document in Cisco IOS Release 12.2(2)T and CNS Flow-Through Provisioning feature document in Cisco IOS Release 12.2(8)T.

SUMMARY STEPS

1. enable

2. configure terminal

3. cns event {hostname | ip-address} [port-number] [encrypt] [backup] [failover-time seconds] [keepalive seconds retry-count] [source ip-address] [force-fmt1]

4. cns id type number {dns-reverse | ipaddress | mac-address} [event] [image]
or
cns id {hardware-serial | hostname | string text} [event] [image]

5. cns image [server server-url [status status-url]]

6. cns image password image-password

7. exit

DETAILED STEPS
Command or Action

Purpose

Step 1

enable
Example:

Router> enable

Enables privileged EXEC mode.

•Enter your password if prompted.

Step 2

configure terminal
Example:

Router# configure terminal

Enters global configuration mode.

Step 3

cns event {hostname | ip-address} [port-number] [encrypt] [backup] [failover-time seconds] [keepalive seconds retry-count] [source ip-address] [force-fmt1]
Example:

Router(config)# cns event 10.20.2.4

Configures the CNS event gateway, which provides CNS event services to Cisco IOS clients.

•The CNS event agent must be configured before the CNS image agent can use the CNS Event Bus.
Step 4
cns id type number {dns-reverse | ipaddress | mac-address} [event] [image]
or

cns id {hardware-serial | hostname | string text} [event] [image]
Example:

Router(config)# cns id fastethernet 0/1 ipaddress image
or

Example:

Router(config)# cns id hardware-serial image
Specifies a unique CNS ID, and interface type and number from which to retrieve the unique ID.

or

Specifies a unique CNS ID assigned from the hardware serial number, device host name, or an arbitrary text string.

The following information applies to either version of the syntax.

•Use the event keyword to specify an event agent ID.

•Use the image keyword to specify an image agent ID.

•If no keywords are used, the configuration agent ID is configured.
Step 5

cns image [server server-url] status status-url
Example:

Router(config)# cns image

Enables CNS image agent services.

•If the server keyword and argument are not specified, the CNS image agent process starts and listens for events on the CNS Event Bus.

Step 6

cns image password password
Example:

Router(config)# cns image password abctext

(Optional) Specifies a password for CNS image agent services.

•If a password is configured, the password is included with the image ID in CNS image agent messages sent out by the image agent. The receiver of these messages can use this information to authenticate the sending device.

Step 7

exit
Example:

Router(config)# exit

Exits global configuration mode, and returns the router to privileged EXEC mode.
Troubleshooting Tips

•Use the show cns event connections command to check that the CNS event agent is connected to the CNS event gateway.

•Use the show cns event subject command to check that the image agent subject names are registered. Subject names for the CNS image agent begin with cisco.mgmt.cns.image.

Polling the Server Using the CLI

Use this task to poll the image distribution server using HTTP or HTTPS.

Prerequisites

This task assumes that you have already configured the CNS image agent using the tasks in the "Configuring the CNS Image Agent Using the CLI" section.

SUMMARY STEPS

1. enable

2. cns image retrieve [server server-url [status status-url]]

DETAILED STEPS

Command or Action

Purpose

Step 1

enable
Example:

Router> enable

Enables privileged EXEC mode.

•Enter your password if prompted.

Step 2

cns image retrieve [server server-url [status status-url]]
Example:

Router# cns image retrieve https://10.19.2.3/imgsvr/ status https://10.19.2.3/imgsvr/status/

Contacts a Cisco CNS image distribution server and downloads a new image if a new image exists.

•Use the optional status keyword and status-url argument to specify the URL of a web server to which status messages are written.

•If the server and status keywords are not specified, the server and status URLs configured with the cns image command are used.

Note We recommend using the cns trusted-server command to specify the host part of the server or status URL as a trusted server.

Troubleshooting Tips

•If the web server appears to be down, use the ping command to check connectivity.

•If using HTTP, use the show ip http client all command to display information about HTTP clients and connections.

Polling the Server Using Command Scheduler

Use this task to set up Command Scheduler policy lists of EXEC CNS commands and configure a Command Scheduler occurrence to specify the time or interval after which the CNS commands will run.

Command Scheduler Policy Lists

Policy lists consist of one or more lines of fully qualified EXEC CLI commands to be run at the same time. Create a separate policy list for commands to be run on a different schedule. No editor function is available and the policy list is run in the order in which it was configured. To delete an entry, use the no form of the cli command followed by the appropriate EXEC command. If an existing policy list name is used, new entries are added to the end of the policy list. To view entries in a policy list, use the show running-config command. If a policy list is only scheduled to run once, it will not be displayed by the show running-config command after it has run.

Policy lists can be configured after the policy list has been scheduled, but each policy list must be configured before it is scheduled to run.

Prerequisites

The EXEC CLI commands to be run by Command Scheduler must be tested on the routing device to determine if it will run without generating a prompt or allowing execution interruption by keystrokes. Initial testing is important because Command Scheduler will delete the entire policy list if any CLI syntax fails. Removing the policy list ensures that any CLI dependencies will not generate more errors.

SUMMARY STEPS

1. enable

2. configure terminal

3. kron policy-list list-name

4. cli command

5. exit

6. kron occurrence occurrence-name [user user-name] {in [[numdays:]numhours:]nummin | at hours:min [[month] day-of-month] [day-of-week]} {oneshot | recurring}

7. policy-list list-name

8. exit

DETAILED STEPS

Command or Action

Purpose

Step 1

enable
Example:

Router> enable

Enables privileged EXEC mode.

•Enter your password if prompted.

Step 2

configure terminal
Example:

Router# configure terminal

Enters global configuration mode.

Step 3

kron policy-list list-name
Example:

Router(config)# kron policy-list cns-weekly

Specifies a name for a new or existing Command Scheduler policy list and enters kron-policy configuration mode.

•If the list-name is new, a new policy list structure is created.

•If the list-name exists, the existing policy list structure is accessed. The policy list is run in configured order with no editor function.

Step 4

cli command
Example:

Router(config-kron-policy)# cli cns image retrieve server https://10.19.2.3/cnsweek/ status https://10.19.2.3/cnsstatus/week/

Specifies the fully-qualified EXEC command and associated syntax to be added as an entry in the specified Command Scheduler policy list.

•Each entry is added to the policy list in the order in which it is configured.

•Repeat this step to add other EXEC CLI commands to a policy list to be executed at the same time or interval.

Note EXEC commands that generate a prompt or can be terminated using keystrokes will cause an error.

Step 5

exit
Example:

Router(config-kron-policy)# exit

Exits kron-policy configuration mode, and returns the router to global configuration mode.

Step 6

kron occurrence occurrence-name [user user] {in [[numdays:]numhours:]nummin | at hours:min [[month] day-of-month] [day-of-week]} {oneshot | recurring}
Example:

Router(config)# kron occurrence may user sales at 6:30 may 20 oneshot

Specifies a name and schedule for a new or existing Command Scheduler occurrence and enters kron-occurrence configuration mode.

•If the list-name is new, a new occurrence list structure is created.

•If the list-name exists, the existing occurrence structure is accessed. The occurrence is run in configured order with no editor function.

•Use the in keyword to specify a delta time interval with a timer that starts when this command is configured.

•Use the at keyword to specify a calendar date and time.

Step 7

policy-list list-name
Example:

Router(config-kron-occurrence)# policy-list sales-may

Specifies a Command Scheduler policy list.

•Each entry is added to the occurrence list in the order in which it is configured.

Note If the CLI commands in a policy list generate a prompt or can be terminated using keystrokes, an error will be generated and the policy list will be deleted.

Step 8

exit
Example:

Router(config-kron-occurrence)# exit

Exits kron-occurrence configuration mode, and returns the router to global configuration mode.

•Repeat this step one more time to exit global configuration mode.

Troubleshooting CNS Image Agent Operation

This section explains how to troubleshoot CNS image agent issues. The show commands created for the CNS image agent display information that is reset to zero after a successful reload of the device. Depending on the configuration of the image distribution process, the new image may not reload immediately. When a reload is not immediate or has failed, use the CNS image agent show commands to determine whether the image agent has connected to the image distribution server over HTTP or whether the image agent is receiving events from an application over the CNS Event Bus.

SUMMARY STEPS

1. enable

2. show cns image status

3. clear cns image status

4. show cns image connections

5. show cns image inventory

6. debug cns image [agent | all | connection | error]

DETAILED STEPS

Command or Action

Purpose

Step 1

enable
Example:

Router> enable

Enables higher privilege levels, such as privileged EXEC mode.

•Enter your password if prompted.

Step 2

show cns image status
Example:

Router# show cns image status

(Optional) Displays information about the CNS image agent status.

Step 3

clear cns image status
Example:

Router# clear cns image status

(Optional) Clears CNS image agent status statistics.

Step 4

show cns image connections
Example:

Router# show cns image connections

(Optional) Displays information about CNS image management server HTTP or HTTPS connections.

Step 5

show cns image inventory
Example:

Router# show cns image inventory

(Optional) Displays inventory information about the CNS image agent.

•This command displays a dump of XML that would be sent out in response to an image agent inventory request message. The XML output can be used to determine the information requested by an application.

Step 6

debug cns image [agent | all | connection | all]
Example:

Router# debug cns image all

(Optional) Displays debugging messages for CNS image agent services.

Examples

This section provides the following output examples:

•Sample Output for the show cns image status Command

•Sample Output for the show cns image connections Command

•Sample Output for the show cns image inventory Command

•Sample Output for the debug cns image Command

Sample Output for the show cns image status Command

In the following example, status information about the CNS image agent is displayed using the show cns image status privileged EXEC command:
Router# show cns image status
Last upgrade started at 11:45:02.000 UTC Mon May 6 2003
Last upgrade ended at 11:56:04.000 UTC Mon May 6 2003 status SUCCESS
Last successful upgrade ended at 11:56:04.000 UTC Mon May 6 2003
Last failed upgrade ended at 06:32:15.000 UTC Wed Apr 16 2003
Number of failed upgrades: 2
Number of successful upgrades: 6
 messages received: 12
 receive errors: 5
Transmit Status
  TX Attempts:4
    Successes:3         Failures 2
Sample Output for the show cns image connections Command

In the following example, information about the status of the CNS image management HTTP connections is displayed using the show cns image connections privileged EXEC command:
Router# show cns image connections
CNS Image Agent:  HTTP connections
Connection attempts 1
never connected:0   Abrupt disconnect:0 
Last successful connection at 11:45:02.000 UTC Mon May 6 2003
Sample Output for the show cns image inventory Command

In the following example, information about the CNS image agent inventory is displayed using the show cns image inventory privileged EXEC command:
Router> show cns image inventory
Inventory Report 
<imageInventoryReport><deviceName><imageID>Router</imageID><hostName>Router</ho 
IOS (tm) C2600 Software (C2600-I-M), Experimental Version 12.3(20030414:081500)]
Copyright (c) 1986-2003 by cisco Systems, Inc.
Compiled Mon 14-Apr-03 02:03 by engineer</versionString><imageFile>tftp://10.25>
.
.
.
Sample Output for the debug cns image Command

In the following example, debugging messages for all CNS image agent services are displayed using the debug cns image privileged EXEC command. The CNS image agent in this example is connecting to an image server over HTTP. After connecting, the image server asks for an inventory of the Cisco IOS device.
Router# debug cns image all
All cns image debug flags are on
Router# cns image retrieve
May  7 06:11:42.175: CNS Image Agent: set EXEC lock
May  7 06:11:42.175: CNS Image Agent: received message from EXEC
May  7 06:11:42.175: CNS Image Agent: set session lock 1
May  7 06:11:42.175: CNS Image Agent: attempting to send to 
destination(http://10.1.36.8:8080/imgsrv/xgate):
<?xml version="1.0" encoding="UTF-8"?><cnsMessageversion="1.0"> 
<senderCredentials><userName>dvlpr-7200-6</userName></senderCredentials>
<messageID>dvlpr-7200-6_2</messageID><sessionControl><imageSessionStart version="1.0">
<initiatorInfo><trigger>EXEC</trigger><initiatorCredentials><userName>dvlpr-7200-6</userNa
me>
</initiatorCredentials></initiatorInfo></imageSessionStart></sessionControl></cnsMessage>
May  7 06:11:42.175: CNS Image Agent: clear EXEC lock
May  7 06:11:42.175: CNS Image Agent: HTTP message sent 
url:http://10.1.36.8:8080/imgsrv/xgate
May  7 06:11:42.191: CNS Image Agent: response data alloc 4096 bytes
May  7 06:11:42.191: CNS Image Agent: HTTP req data free
May  7 06:11:42.191: CNS Image Agent: response data freed
May  7 06:11:42.191: CNS Image Agent: receive message
<?xml version="1.0" encoding="UTF-8"?>
<cnsMessage version="1.0">
        <senderCredentials>
                <userName>myImageServer.cisco.com</userName>
                <passWord>R0lGODlhcgGSALMAAAQCAEMmCZtuMFQxDS8b</passWord>
        </senderCredentials>
        <messageID>dvlpr-c2600-2-476456</messageID>
        <request>
                <replyTo>
                        <serverReply>http://10.1.36.8:8080/imgsrv/xgate</serverReply>
                </replyTo>
                <imageInventory>
                        <inventoryItemList>
                                <all/>
                        </inventoryItemList>
                </imageInventory>
        </request>
</cnsMessage>
Configuration Examples for the CNS Image Agent

This section contains the following configuration examples:

•Configuring the CNS Image Agent Examples

•Polling the Server Examples

Configuring the CNS Image Agent Examples

In the following example, the CNS image agent parameters are configured using the CLI. An image ID is specified to use the IP address of the FastEthernet interface 0/1, a password is configured for the CNS image agent services, the CNS image upgrade retry interval is set to four minutes, and image management and status servers are configured.
cns id FastEthernet0/1 ipaddress image
cns image retry 240
cns image password abctext
cns image server https://10.21.2.3/cns/imgsvr status https://10.21.2.3/cns/status/
In the following example, the CNS image agent is configured to use the CNS Event Bus. An image ID is specified as the hardware serial number of the networking device, the CNS event agent is enabled with a number of parameters, and the CNS image agent is enabled without any keywords or options. The CNS image agent will listen for events on the CNS Event Bus.
cns id hardware-serial image
cns event 10.21.9.7 11011 keepalive 240 120 failover-time 5
cns image
cns image password abctext
Polling the Server Examples

In the following example, the CNS image agent polls a file server using the cns image retrieve command. Assuming that the CNS image agent is already enabled, the file server and status server paths specified here will overwrite any existing image agent server and status configuration. The new file server will be polled and a new image, if it exists, will be downloaded to the networking device.
cns image retrieve server https://10.19.2.3/cns/ status https://10.19.2.3/cnsstatus/
In the following example, a Command Scheduler policy named cns-weekly is configured to run EXEC CLI involving CNS commands. The policy is then scheduled to run every seven days, one hour and thirty minutes.
kron policy-list cns-weekly
 cli cns image retrieve server https://10.1.2.3/week/ status https://10.1.2.3/status/week/
!
kron occurrence week in 7:1:30 recurring
 policy-list cns-weekly
Where to Go Next

One feature that can be used with the CNS image agent is the Command Scheduler process. See the "Related Documents" section for more details.

Additional References

The following sections provide references related to the CNS image agent:

•Related Documents

•Standards

•MIBs

•RFCs

•Technical Assistance

Related Documents

Related Topic

Document Title

CNS commands: complete command syntax, command mode, defaults, usage guidelines, and examples

"CNS Commands" chapter in the Cisco IOS Configuration Fundamentals Command Reference, Release 12.3

CNS configuration agent

"CNS Configuration Agent" feature document, Release 12.2(2)T

CNS event agent

"CNS Event Agent" feature document, Release 12.2(2)T

CNS flow-through provisioning

"CNS Flow-Through Provisioning" feature document, Release 12.2(8)T

CNS Configuration Engine

Cisco Intelligence Engine 2100 Configuration Registrar Manual, Release 1.1 or higher

Command Scheduler

"Command Scheduler" feature document, Release 12.3(1)

Standards

Standards

Title

No new or modified standards are supported by this feature, and support for existing standards has not been modified by this feature.

—

MIBs

MIBs

MIBs Link

No new or modified MIBs are supported by this feature, and support for existing MIBs has not been modified by this feature.

To locate and download MIBs for selected platforms, Cisco IOS releases, and feature sets, use Cisco MIB Locator found at the following URL:

http://www.cisco.com/go/mibs

RFCs

RFCs

Title

No new or modified RFCs are supported by this feature, and support for existing RFCs has not been modified by this feature.

—

Technical Assistance

Description

Link

Technical Assistance Center (TAC) home page, containing 30,000 pages of searchable technical content, including links to products, technologies, solutions, technical tips, and tools. Registered Cisco.com users can log in from this page to access even more content.

http://www.cisco.com/public/support/tac/home.shtml

Command Reference

This section documents new and modified commands. All other commands used with this feature are documented in the Cisco IOS Release 12.3 command reference publications.

New Commands

•clear cns image connections

•clear cns image status

•cns image

•cns image password

•cns image retrieve

•cns image retry

•debug cns image

•show cns image connections

•show cns image inventory

•show cns image status

Modified Commands

•cns id

clear cns image connections

To clear the CNS image agent connections statistics, use the clear cns image connections command in privileged EXEC mode.

clear cns image connections
Syntax Description

This command has no arguments or keywords.

Defaults

No statistics are cleared.

Command Modes

Privileged EXEC

Command History

Release

Modification

12.3(1)

This command was introduced.

Usage Guidelines

The clear cns image connections command clears all the statistics displayed by the show cns image connections command.

Examples

The following example shows how to clear all of the connection statistics for the CNS image agent:
Router# clear cns image connections
Related Commands

Command

Description

show cns image connections

Displays connection information for the CNS image agent.

clear cns image status

To clear the CNS image agent status statistics, use the clear cns image status command in privileged EXEC mode.

clear cns image status
Syntax Description

This command has no arguments or keywords.

Defaults

No statistics are cleared.

Command Modes

Privileged EXEC

Command History

Release

Modification

12.3(1)

This command was introduced.

Usage Guidelines

The clear cns image status command clears all the statistics displayed by the show cns image status command.

Examples

The following example shows how to clear all of the status statistics for the CNS image agent:
Router# clear cns image status
Related Commands

Command

Description

show cns image status

Displays status information for the CNS image agent.

cns id

To set the unique event ID, config ID, or image ID Cisco IOS device identifier used by CNS services, use the cns id command in global configuration mode. To set the identifier to the host name of the Cisco IOS device, use the no form of this command.

If ID Choice Is IP Address or MAC Address

cns id type number {dns-reverse | ipaddress | mac-address} [event] [image]
no cns id type number {dns-reverse | ipaddress | mac-address} [event] [image]
If ID Choice Is Anything Else

cns id {hardware-serial | hostname | string string} [event] [image]
no cns id {hardware-serial | hostname | string string} [event] [image]
Syntax Description

type number

Type of interface (for example, ethernet, group-async, loopback, or virtual-template) and the interface number. Indicates from which interface the IP or MAC address should be retrieved in order to define the unique ID.

dns-reverse

Uses DNS reverse lookup to retrieve the host name of the Cisco IOS device and assign it as the unique ID.

ipaddress

Uses the IP address specified in the type number arguments as the unique ID.

mac-address

Uses the MAC address specified in the type number arguments as the unique ID.

event

(Optional) Sets this ID to be the event ID value, which is used to identify the Cisco IOS device for CNS event services. If both optional keywords are omitted, the event ID is set to the host name of the Cisco IOS device.

image

(Optional) Sets this ID to be the image ID value, which is used to identify the Cisco IOS device for CNS image agent services. If both optional keywords are omitted, the image ID is set to the host name of the Cisco IOS device.

hardware-serial

Uses the hardware serial number as the unique ID.

hostname

Uses the host name as the unique ID. This is the system default.

string string

Uses an arbitrary text string—typically the host name—as the unique ID.

Defaults

The system defaults to the host name of the Cisco IOS device as the unique ID.

Command Modes

Global configuration

Command History

Release

Modification

12.2(2)XB

This command was introduced on Cisco IAD2420 series IADs.

12.2(8)T

This command was integrated into Cisco IOS Release 12.2(8)T.

12.3(1)

The optional image keyword was added to set an image ID.

Usage Guidelines

Use this command to set the unique ID to the CNS configuration agent, which then pulls the initial configuration template to the Cisco IOS device during bootup.

You can set one or all three IDs: the config ID value for CNS configuration services, the event ID value for CNS event services, and the image ID value for CNS image agent services. To set all values, use the command three times.

To set the CNS event ID to the host name of the Cisco IOS device, use the no form of this command with the event keyword. To set the CNS config ID to the host name of the Cisco IOS device, use the no form of this command without the event keyword. To set the CNS image ID to the host name of the Cisco IOS device, use the no form of this command with the image keyword.

Examples

The following example shows how to pass the host name of the Cisco IOS device as the config ID value:
Router(config)# cns id hostname
The following example shows how to pass the hardware serial number of the Cisco IOS device as the event ID value:
Router(config)# cns id hardware-serial event
The following example shows how to pass the IP address of Ethernet interface 0/1 as the image ID value:
Router(config)# cns id ethernet 0/1 image
Related Commands

Command

Description

cns event

Enables the CNS event gateway, which provides CNS event services to Cisco IOS clients.

cns image

Enables the CNS image agent services to Cisco IOS clients.

cns image

To configure the CNS image agent services, use the cns image command in global configuration mode. To disable the use of CNS image agent services, use the no form of this command.

cns image [server server-url] status status-url
no cns image [server server-url] status status-url
Syntax Description

server

(Optional) Specifies an image distribution server to contact for information about an updated image to be downloaded.

server-url

(Optional) The URL used to contact an image distribution server. An IP address or domain name can be used.

status

Specifies that any status messages generated by CNS image agent operations will be sent to the URL specified by the status-url argument.

status-url

The URL of a web server to which status messages are written.

Defaults

When configured, the CNS image agent always listens for image events on the CNS Event Bus server.

Command Modes

Global configuration

Command History

Release

Modification

12.3(1)

This command was introduced.

Usage Guidelines

Use the cns image command to start the CNS image agent process and to listen for image-related events on the CNS Event Bus.

If the optional server details are specified, the CNS image agent uses the server URL to contact the image management server. If no server details are specified, the URL for the image server must be supplied using one of the following three methods. The first method is to specify the image server using the server options on the cns image retrieve command. The second method is to use the server configured by the CNS event agent and stored as an image server event that can be received from the CNS Event Bus. The third method does not require a server URL because it uses CNS Event Bus mode. If server details are still missing, an error message will be generated asking for a server URL.

Examples

The following example shows how to enable the CNS image agent services and configure a path to the image distribution server and a status messages server:
Router(config)# cns image server https://10.20.2.3:8080/cns/imageserver/ status 
https://10.20.2.3:8080/cns/imageserver/messages/
Related Commands

Command

Description

show cns image status

Displays information about the CNS image agent status.

cns image password

To configure a password to use with the CNS image agent services, use the cns image password command in global configuration mode. To disable the use of a password, use the no form of this command.

cns image password image-password
no cns image password image-password
Syntax Description

image-password

Password to be used for CNS image agent services.

Defaults

No password is used with the CNS image agent services.

Command Modes

Global configuration

Command History

Release

Modification

12.3(1)

This command was introduced.

Usage Guidelines

Use this command to create a password that is sent along with the image ID in all CNS image agent messages. The receiver of these messages can use this information to authenticate the sending device. This password may be different from the username and password used for HTTP basic authentication configured with other CNS image agent commands.

Examples

The following example shows how to configure a password to be used for the CNS image agent services:
Router(config)# cns image password textabc
Related Commands

Command

Description

cns id

Specifies the unique event ID, config ID, or image ID used by CNS services.

cns image retrieve

To contact a CNS image distribution server and download a new image if a new image exists, use the cns image retrieve command in privileged EXEC mode.

cns image retrieve [server server-url [status status-url]]
Syntax Description

server

(Optional) Specifies an image distribution server to contact for information about an updated image to be downloaded. If the server keyword is not specified, the server path configured in the cns image command is used. If no server path has been configured, an error is displayed.

server-url

(Optional) The URL used to contact an image distribution server. If the server-url argument is not specified, the URL path configured in the cns image command is used. If no URL has been configured, an error is displayed.

status

(Optional) Specifies that any status messages generated by this command will be sent to the URL specified by the status-url argument.

status-url

(Optional) The URL of a web server to which status messages are written.

Defaults

If the server keyword and server-url argument are not specified, the server path configured in the cns image command is used. If no server path has been configured, an error is displayed.

Command Modes

Privileged EXEC

Command History

Release

Modification

12.3(1)

This command was introduced.

Usage Guidelines

You must enable the CNS image agent services using the cns image command before configuring this command.

Use this command to poll an image distribution server and download a new image to the Cisco IOS device if a new image exists.

Examples

The following example shows how to configure the CNS image agent to access the image distribution server at 10.19.2.3 and download a new image if a new image exists:
Router# cns image retrieve server https://10.20.2.3:8080/cns/imageserver/ status 
https://10.20.2.3:8080/cns/imageserver/messages/
Related Commands

Command

Description

cns image

Enables CNS image agent services.

cns trusted-server

Specifies a trusted server for CNS agents.

show cns image status

Displays information about the CNS image agent status.

cns image retry

To set the CNS image upgrade retry interval, use the cns image retry command in global configuration mode. To restore the default value, use the no form of this command.

cns image retry seconds
no cns image retry seconds
Syntax Description

seconds

(Optional) Interval in seconds from 0 to 65535. The default is 60 seconds.

Defaults

Retry interval is 60 seconds.

Command Modes

Global configuration

Command History

Release

Modification

12.3(1)

This command was introduced.

Usage Guidelines

Use this command to set an interval after which the CNS image agent will retry an image upgrade operation if the original upgrade attempt failed.

Examples

The following example shows how to set the CNS image upgrade interval to 240 seconds:
Router(config)# cns image retry 240
Related Commands

Command

Description

cns image

Enables CNS image agent services.

debug cns image

To display debugging messages about CNS image agent services, use the debug cns image command in privileged EXEC mode. To disable debugging output, use the no form of this command.

debug cns image {agent | all | connection | error}
no debug cns image {agent | all | connection | error}
Syntax Description

agent

Displays debugging messages related to the image agent.

all

Displays all debugging messages.

connection

Displays debugging messages related to image agent connections.

error

Displays debugging messages related to errors generated by image agent services.

Defaults

If no keyword is specified, all debugging messages are displayed.

Command Modes

Privileged EXEC

Command History

Release

Modification

12.3(1)

This command was introduced.

Usage Guidelines

Use the debug cns image command to troubleshoot CNS image agent services.

Examples

The following example shows debugging messages for all CNS image agent services. The CNS image agent in this example is connecting to an image server over HTTP. After connecting, the image server asks for an inventory of the Cisco IOS device.
Router# debug cns image all
All cns image debug flags are on
Router# cns image retrieve
May  7 06:11:42.175: CNS Image Agent: set EXEC lock
May  7 06:11:42.175: CNS Image Agent: received message from EXEC
May  7 06:11:42.175: CNS Image Agent: set session lock 1
May  7 06:11:42.175: CNS Image Agent: attempting to send to 
destination(http://10.1.36.8:8080/imgsrv/xgate):
<?xml version="1.0" encoding="UTF-8"?><cnsMessageversion="1.0"> 
<senderCredentials><userName>dvlpr-7200-6</userName></senderCredentials>
<messageID>dvlpr-7200-6_2</messageID><sessionControl><imageSessionStart version="1.0">
<initiatorInfo><trigger>EXEC</trigger><initiatorCredentials><userName>dvlpr-7200-6</userNa
me>
</initiatorCredentials></initiatorInfo></imageSessionStart></sessionControl></cnsMessage>
May  7 06:11:42.175: CNS Image Agent: clear EXEC lock
May  7 06:11:42.175: CNS Image Agent: HTTP message sent 
url:http://10.1.36.8:8080/imgsrv/xgate
May  7 06:11:42.191: CNS Image Agent: response data alloc 4096 bytes
May  7 06:11:42.191: CNS Image Agent: HTTP req data free
May  7 06:11:42.191: CNS Image Agent: response data freed
May  7 06:11:42.191: CNS Image Agent: receive message
<?xml version="1.0" encoding="UTF-8"?>
<cnsMessage version="1.0">
        <senderCredentials>
                <userName>myImageServer.cisco.com</userName>
                <passWord>R0lGODlhcgGSALMAAAQCAEMmCZtuMFQxDS8b</passWord>
        </senderCredentials>
        <messageID>dvlpr-c2600-2-476456</messageID>
        <request>
                <replyTo>
                        <serverReply>http://10.1.36.8:8080/imgsrv/xgate</serverReply>
                </replyTo>
                <imageInventory>
                        <inventoryItemList>
                                <all/>
                        </inventoryItemList>
                </imageInventory>
        </request>
</cnsMessage>
Related Commands

Command

Description

cns image

Enables CNS image agent services.

show cns image connections

To display the status of the CNS image management server HTTP connections, use the show cns image connections command in privileged EXEC mode.

show cns image connections
Syntax Description

This command has no arguments or keywords.

Command Modes

Privileged EXEC

Command History

Release

Modification

12.3(1)

This command was introduced.

Usage Guidelines

Use the show cns image connections command when troubleshooting HTTP connection problems with the CNS image server. The output displays the following information:

•Number of connection attempts

•Number of connections that were never connected and those that were abruptly disconnected

•Date and time of last successful connection

Examples

The following is sample output from the show cns image connections command:
Router# show cns image connections
CNS Image Agent:  HTTP connections
Connection attempts 1
never connected:0   Abrupt disconnect:0 
Last successful connection at 11:45:02.000 UTC Mon May 6 2003
Related Commands

Command

Description

show cns image inventory

Displays inventory information about the CNS image agent.

show cns image status

Displays status information about the CNS image agent.

show cns image inventory

To provide a dump of CNS image inventory information in XML format, use the show cns image inventory command in privileged EXEC mode.

show cns image inventory
Syntax Description

This command has no arguments or keywords.

Command Modes

Privileged EXEC

Command History

Release

Modification

12.3(1)

This command was introduced.

Usage Guidelines

To view the XML output in a better format, paste the content into a text file and use an XML viewing tool.

Examples

The following is sample output from the show cns image inventory command:
Router# show cns image inventory
Inventory Report 
<imageInventoryReport><deviceName><imageID>Router</imageID><hostName>Router</ho 
IOS (tm) C2600 Software (C2600-I-M), Experimental Version 12.3(20030414:081500)]
Copyright (c) 1986-2003 by cisco Systems, Inc.
Compiled Mon 14-Apr-03 02:03 by engineer</versionString><imageFile>tftp://10.25>
Related Commands

Command

Description

show cns image connections

Displays connection information for the CNS image agent.

show cns image status

Displays status information about the CNS image agent.

show cns image status

To display status information about the CNS image agent, use the show cns image status command in privileged EXEC mode.

show cns image status
Syntax Description

This command has no arguments or keywords.

Command Modes

Privileged EXEC

Command History

Release

Modification

12.3(1)

This command was introduced.

Usage Guidelines

Use this command to display the following status information about the CNS image agent:

•Start date and time of last upgrade

•End date and time of last upgrade

•End date and time of last successful upgrade

•End date and time of last failed upgrade

•Number of failed upgrades

•Number of successful upgrades with number of received messages and errors

•Transmit status with number of attempts, successes, and failures

Examples

The following is sample output from the show cns image status command::
Router# show cns image status
Last upgrade started at 11:45:02.000 UTC Mon May 6 2003
Last upgrade ended at 11:56:04.000 UTC Mon May 6 2003 status SUCCESS
Last successful upgrade ended at 00:00:00.000 UTC Mon May 6 2003
Last failed upgrade ended at 00:00:00.000 UTC Wed Apr 16 2003
Number of failed upgrades: 2
Number of successful upgrades: 6
 messages received: 12
 receive errors: 5
Transmit Status
  TX Attempts:4
    Successes:3         Failures 2
Related Commands

Command

Description

show cns image connections

Displays connection information for the CNS image agent.

show cns image inventory

Displays image inventory information in XML format.

Copyright © 2003 Cisco Systems, Inc. All rights reserved.

Cisco IOS Software Releases 12.3 Mainline

CNS Image Agent

Hierarchical Navigation

Downloads

Table Of Contents

CNS Image Agent

Contents

Prerequisites for the CNS Image Agent

Restrictions for the CNS Image Agent

Information About the CNS Image Agent

CNS

CNS Image Agent

How to Configure the CNS Image Agent

Configuring the CNS Image Agent Using the CLI

CNS Image Agent ID

Prerequisites

SUMMARY STEPS

DETAILED STEPS

What to Do Next

Configuring the CNS Image Agent to Use the CNS Event Bus

SUMMARY STEPS

DETAILED STEPS

Troubleshooting Tips

Polling the Server Using the CLI

Prerequisites

SUMMARY STEPS

DETAILED STEPS

Troubleshooting Tips

Polling the Server Using Command Scheduler

Command Scheduler Policy Lists

Prerequisites

SUMMARY STEPS

DETAILED STEPS

Troubleshooting CNS Image Agent Operation

SUMMARY STEPS

DETAILED STEPS

Examples

Sample Output for the show cns image status Command

Sample Output for the show cns image connections Command

Sample Output for the show cns image inventory Command

Sample Output for the debug cns image Command

Configuration Examples for the CNS Image Agent

Configuring the CNS Image Agent Examples

Polling the Server Examples

Where to Go Next

Additional References

Related Documents

Standards

MIBs

RFCs

Technical Assistance

Command Reference

clear cns image connections

Syntax Description

Defaults

Command Modes

Command History

Usage Guidelines

Examples

Related Commands

clear cns image status

Syntax Description

Defaults

Command Modes

Command History

Usage Guidelines

Examples

Related Commands

cns id

Syntax Description

Defaults

Command Modes

Command History

Usage Guidelines

Examples

Related Commands

cns image

Syntax Description

Defaults

Command Modes